Trait boa_engine::context::HostHooks

pub trait HostHooks {
    // Provided methods
    fn make_job_callback(
        &self,
        callback: JsFunction,
        _context: &mut Context
    ) -> JobCallback { ... }
    fn call_job_callback(
        &self,
        job: JobCallback,
        this: &JsValue,
        args: &[JsValue],
        context: &mut Context
    ) -> JsResult<JsValue> { ... }
    fn promise_rejection_tracker(
        &self,
        _promise: &JsObject,
        _operation: OperationType,
        _context: &mut Context
    ) { ... }
    fn ensure_can_compile_strings(
        &self,
        _realm: Realm,
        _parameters: &[JsString],
        _body: &JsString,
        _direct: bool,
        _context: &mut Context
    ) -> JsResult<()> { ... }
    fn has_source_text_available(
        &self,
        _function: &JsFunction,
        _context: &mut Context
    ) -> bool { ... }
    fn ensure_can_add_private_element(
        &self,
        _o: &JsObject,
        _context: &mut Context
    ) -> JsResult<()> { ... }
    fn create_global_object(&self, intrinsics: &Intrinsics) -> JsObject { ... }
    fn create_global_this(&self, _intrinsics: &Intrinsics) -> Option<JsObject> { ... }
    fn utc_now(&self) -> i64 { ... }
    fn local_timezone_offset_seconds(&self, unix_time_seconds: i64) -> i32 { ... }
    fn max_buffer_size(&self, _context: &mut Context) -> u64 { ... }
}

Host Hooks customizable by the host code or engine.

Every hook contains on its Requirements section the spec requirements that the hook must abide to for spec compliance.

Usage

Implement the trait for a custom struct (maybe with additional state), overriding the methods that need to be redefined:

use boa_engine::{
    context::{Context, ContextBuilder, HostHooks},
    realm::Realm,
    JsNativeError, JsResult, JsString, Source,
};

struct Hooks;

impl HostHooks for Hooks {
    fn ensure_can_compile_strings(
        &self,
        _realm: Realm,
        _parameters: &[JsString],
        _body: &JsString,
        _direct: bool,
        _context: &mut Context,
    ) -> JsResult<()> {
        Err(JsNativeError::typ()
            .with_message("eval calls not available")
            .into())
    }
}

let context =
    &mut ContextBuilder::new().host_hooks(&Hooks).build().unwrap();
let result = context.eval(Source::from_bytes(r#"eval("let a = 5")"#));
assert_eq!(
    result.unwrap_err().to_string(),
    "TypeError: eval calls not available"
);

Provided Methods

fn make_job_callback( &self, callback: JsFunction, _context: &mut Context ) -> JobCallback

HostMakeJobCallback ( callback )

Requirements

• It must return a JobCallback Record whose [[Callback]] field is callback.

fn call_job_callback( &self, job: JobCallback, this: &JsValue, args: &[JsValue], context: &mut Context ) -> JsResult<JsValue>

HostCallJobCallback ( jobCallback, V, argumentsList )

Requirements

• It must perform and return the result of Call(jobCallback.[[Callback]], V, argumentsList).

fn promise_rejection_tracker( &self, _promise: &JsObject, _operation: OperationType, _context: &mut Context )

HostPromiseRejectionTracker ( promise, operation )

Requirements

• It must complete normally (i.e. not return an abrupt completion). This is already ensured by the return type.

fn ensure_can_compile_strings( &self, _realm: Realm, _parameters: &[JsString], _body: &JsString, _direct: bool, _context: &mut Context ) -> JsResult<()>

HostEnsureCanCompileStrings ( calleeRealm, parameterStrings, bodyString, direct )

Requirements

• If the returned Completion Record is a normal completion, it must be a normal completion containing unused. This is already ensured by the return type.

fn has_source_text_available( &self, _function: &JsFunction, _context: &mut Context ) -> bool

HostHasSourceTextAvailable ( func )

Requirements

• It must be deterministic with respect to its parameters. Each time it is called with a specific func as its argument, it must return the same result.

fn ensure_can_add_private_element( &self, _o: &JsObject, _context: &mut Context ) -> JsResult<()>

HostEnsureCanAddPrivateElement ( O )

Requirements

• If O is not a host-defined exotic object, this abstract operation must return NormalCompletion(unused) and perform no other steps.
• Any two calls of this abstract operation with the same argument must return the same kind of Completion Record.
• This abstract operation should only be overriden by ECMAScript hosts that are web browsers.

fn create_global_object(&self, intrinsics: &Intrinsics) -> JsObject

Creates the global object of a new Context from the initial intrinsics.

Equivalent to the step 7 of InitializeHostDefinedRealm ( ).

fn create_global_this(&self, _intrinsics: &Intrinsics) -> Option<JsObject>

Creates the global this of a new Context from the initial intrinsics.

Equivalent to the step 8 of InitializeHostDefinedRealm ( ).

fn utc_now(&self) -> i64

Gets the current UTC time of the host.

Defaults to using OffsetDateTime::now_utc on all targets, which can cause panics if the target doesn’t support SystemTime::now.

fn local_timezone_offset_seconds(&self, unix_time_seconds: i64) -> i32

Returns the offset of the local timezone to the utc timezone in seconds.

fn max_buffer_size(&self, _context: &mut Context) -> u64

Gets the maximum size in bits that can be allocated for an ArrayBuffer or a SharedArrayBuffer.

This hook will be called before any buffer allocation, which allows to dinamically change the maximum size at runtime. By default, this is set to 1.5GiB per the recommendations of the specification:

If a host is multi-tenanted (i.e. it runs many ECMAScript applications simultaneously), such as a web browser, and its implementations choose to implement in-place growth by reserving virtual memory, we recommend that both 32-bit and 64-bit implementations throw for values of “maxByteLength” ≥ 1GiB to 1.5GiB. This is to reduce the likelihood a single application can exhaust the virtual memory address space and to reduce interoperability risk.

Implementors

impl HostHooks for DefaultHooks