Struct boa_engine::Context

pub struct Context<'host> { /* 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::{
    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("x", 12, Attribute::READONLY)
    .build();
context.register_global_property("arg", arg, Attribute::all());

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

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

Implementations

impl<'host> Context<'host>

pub fn builder() -> ContextBuilder<'static, 'static, 'static, 'static>

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

pub fn eval<R: Read>(&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::{
    object::ObjectInitializer,
    property::{Attribute, PropertyDescriptor},
    Context,
};

let mut context = Context::default();

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

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

pub fn register_global_callable( &mut self, name: &str, 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: &str, 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<T>(&mut self) -> JsResult<()>where T: Class,

Register a global class of type T, where T implements Class.

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

Example

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

impl Class for MyClass {
   // ...
}

context.register_global_class::<MyClass>();

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 need to ensure that jobs are executed concurrently, you can 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 const fn root_shape(&self) -> &RootShape

Get the RootShape.

pub fn host_hooks(&self) -> MaybeShared<'host, dyn HostHooks>

Gets the host hooks.

pub fn job_queue(&self) -> MaybeShared<'host, dyn JobQueue>

Gets the job queue.

pub fn module_loader(&self) -> MaybeShared<'host, 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.

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.