Struct boa_engine::context::Context

pub struct Context { /* private fields */ }

ECMAScript context. It is the primary way to interact with the runtime.

Contexts constructed in a thread share the same runtime, therefore it is possible to share objects from one context to another context, but they have to be in the same thread.

Examples

Execute Function of Script File

use boa_engine::{
    js_string,
    object::ObjectInitializer,
    property::{Attribute, PropertyDescriptor},
    Context, Source,
};

let script = r#"
    function test(arg1) {
        if(arg1 != null) {
            return arg1.x;
        }
        return 112233;
    }
"#;

let mut context = Context::default();

// Populate the script definition to the context.
context.eval(Source::from_bytes(script)).unwrap();

// Create an object that can be used in eval calls.
let arg = ObjectInitializer::new(&mut context)
    .property(js_string!("x"), 12, Attribute::READONLY)
    .build();
context
    .register_global_property(js_string!("arg"), arg, Attribute::all())
    .expect("property shouldn't exist");

let value = context.eval(Source::from_bytes("test(arg)")).unwrap();

assert_eq!(value.as_number(), Some(12.0))

Implementations

impl Context

pub fn builder() -> ContextBuilder

Create a new ContextBuilder to specify the Interner and/or the icu data provider.

pub fn eval<R: ReadChar>(&mut self, src: Source<'_, R>) -> JsResult<JsValue>

Evaluates the given source by compiling down to bytecode, then interpreting the bytecode into a value.

Examples

let mut context = Context::default();

let source = Source::from_bytes("1 + 3");
let value = context.eval(source).unwrap();

assert!(value.is_number());
assert_eq!(value.as_number().unwrap(), 4.0);

Note that this won’t run any scheduled promise jobs; you need to call Context::run_jobs on the context or JobQueue::run_jobs on the provided queue to run them.

pub fn optimize_statement_list( &mut self, statement_list: &mut StatementList ) -> OptimizerStatistics

Applies optimizations to the StatementList inplace.

pub fn register_global_property<K, V>( &mut self, key: K, value: V, attribute: Attribute ) -> JsResult<()>

where K: Into<PropertyKey>, V: Into<JsValue>,

Register a global property.

It will return an error if the property is already defined.

Example

use boa_engine::{
    js_string,
    object::ObjectInitializer,
    property::{Attribute, PropertyDescriptor},
    Context,
};

let mut context = Context::default();

context
    .register_global_property(
        js_string!("myPrimitiveProperty"),
        10,
        Attribute::all(),
    )
    .expect("property shouldn't exist");

let object = ObjectInitializer::new(&mut context)
    .property(js_string!("x"), 0, Attribute::all())
    .property(js_string!("y"), 1, Attribute::all())
    .build();
context
    .register_global_property(
        js_string!("myObjectProperty"),
        object,
        Attribute::all(),
    )
    .expect("property shouldn't exist");

pub fn register_global_callable( &mut self, name: JsString, length: usize, body: NativeFunction ) -> JsResult<()>

Register a global native callable.

The function will be both constructable (call with new <name>()) and callable (call with <name>()).

The function will be bound to the global object with writable, non-enumerable and configurable attributes. The same as when you create a function in JavaScript.

Note

If you wish to only create the function object without binding it to the global object, you can use the FunctionObjectBuilder API.

pub fn register_global_builtin_callable( &mut self, name: JsString, length: usize, body: NativeFunction ) -> JsResult<()>

Register a global native function that is not a constructor.

The function will be bound to the global object with writable, non-enumerable and configurable attributes. The same as when you create a function in JavaScript.

Note

The difference to Context::register_global_callable is, that the function will not be constructable. Usage of the function as a constructor will produce a TypeError.

pub fn register_global_class<C: Class>(&mut self) -> JsResult<()>

Registers a global class C in the currently active realm.

Errors if the class has already been registered.

Example

#[derive(Debug, Trace, Finalize)]
struct MyClass;

impl Class for MyClass {
   // ...
}

context.register_global_class::<MyClass>()?;

pub fn unregister_global_class<C: Class>( &mut self ) -> JsResult<Option<StandardConstructor>>

Removes the global class C from the currently active realm, returning the constructor and prototype of the class if C was registered.

Note

This makes the constructor return an error on further calls, but note that this won’t protect static properties from being accessed within variables that stored the constructor before being unregistered. If you need that functionality, you can use a static accessor that first checks if the class is registered (Context::has_global_class) before returning the static value.

Example

#[derive(Debug, Trace, Finalize)]
struct MyClass;

impl Class for MyClass {
   // ...
}

context.register_global_class::<MyClass>()?;
// ... code
context.unregister_global_class::<MyClass>()?;

pub fn has_global_class<C: Class>(&self) -> bool

Checks if the currently active realm has the global class C registered.

pub fn get_global_class<C: Class>(&self) -> Option<StandardConstructor>

Gets the constructor and prototype of the global class C if the currently active realm has that class registered.

pub const fn interner(&self) -> &Interner

Gets the string interner.

pub fn interner_mut(&mut self) -> &mut Interner

Gets a mutable reference to the string interner.

pub fn global_object(&self) -> JsObject

Returns the global object.

pub fn intrinsics(&self) -> &Intrinsics

Returns the currently active intrinsic constructors and objects.

pub const fn realm(&self) -> &Realm

Returns the currently active realm.

pub const fn optimizer_options(&self) -> OptimizerOptions

Get optimizer options.

pub fn set_optimizer_options(&mut self, optimizer_options: OptimizerOptions)

Enable or disable optimizations

pub fn strict(&mut self, strict: bool)

Changes the strictness mode of the context.

pub fn enqueue_job(&mut self, job: NativeJob)

Enqueues a NativeJob on the JobQueue.

pub fn run_jobs(&mut self)

Runs all the jobs in the job queue.

pub async fn run_jobs_async(&mut self)

Asynchronously runs all the jobs in the job queue.

Note

Concurrent job execution cannot be guaranteed by the engine, since this depends on the specific handling of each JobQueue. If you want to execute jobs concurrently, you must provide a custom implementor of JobQueue to the context.

pub fn clear_kept_objects(&mut self)

Abstract operation ClearKeptObjects.

Clears all objects maintained alive by calls to the AddToKeptObjects abstract operation, used within the WeakRef constructor.

pub fn stack_trace(&self) -> impl Iterator<Item = &CallFrame>

Retrieves the current stack trace of the context.

pub fn enter_realm(&mut self, realm: Realm) -> Realm

Replaces the currently active realm with realm, and returns the old realm.

pub fn create_realm(&mut self) -> JsResult<Realm>

Create a new Realm with the default global bindings.

pub const fn root_shape(&self) -> &RootShape

Get the RootShape.

pub fn host_hooks(&self) -> &'static dyn HostHooks

Gets the host hooks.

pub fn job_queue(&self) -> Rc<dyn JobQueue>

Gets the job queue.

pub fn module_loader(&self) -> Rc<dyn ModuleLoader>

Gets the module loader.

pub const fn runtime_limits(&self) -> RuntimeLimits

Get the RuntimeLimits.

pub fn set_runtime_limits(&mut self, runtime_limits: RuntimeLimits)

Set the RuntimeLimits.

pub fn runtime_limits_mut(&mut self) -> &mut RuntimeLimits

Get a mutable reference to the RuntimeLimits.

pub fn can_block(&self) -> bool

Returns true if this context can be suspended by an Atomics.wait call.

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Context

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Context

fn drop(&mut self)

Executes the destructor for this type.