NativeCallContext

If the first parameter of a function is of type rhai::NativeCallContext, then it is treated specially by the Engine.

NativeCallContext is a type that encapsulates the current call context of a Rust function call and exposes the following.

MethodReturn typeDescription
engine()&Enginethe current Engine, with all configurations and settings.
This is sometimes useful for calling a script-defined function within the same evaluation context using Engine::call_fn, or calling a function pointer.
fn_name()&strname of the function called (useful when the same Rust function is mapped to multiple Rhai-callable function names)
source()Option<&str>reference to the current source, if any
position()Positionposition of the function call
call_level()usizethe current nesting level of function calls
tag()&Dynamicreference to the custom state that is persistent during the current run
iter_imports()impl Iterator<Item = (&str,&Module)>iterator of the current stack of modules imported via import statements, in reverse order (i.e. later modules come first)
global_runtime_state()&GlobalRuntimeStatereference to the current global runtime state (including the stack of modules imported via import statements); requires the internals feature
iter_namespaces()impl Iterator<Item =&Module>iterator of the namespaces (as modules) containing all script-defined functions, in reverse order (i.e. later modules come first)
namespaces()&[&Module]reference to the namespaces (as modules) containing all script-defined functions; requires the internals feature
call_fn(...)Result<T, Box<EvalAltResult>>call a function with the supplied arguments, casting the result into the required type
call_native_fn(...)Result<T, Box<EvalAltResult>>call a registered native Rust function with the supplied arguments, casting the result into the required type
call_fn_raw(...)Result<Dynamic, Box<EvalAltResult>>call a function with the supplied arguments; this is an advanced method
call_native_fn_raw(...)Result<Dynamic, Box<EvalAltResult>>call a registered native Rust function with the supplied arguments; this is an advanced method

Example – Implement Safety Checks

The native call context is useful for protecting a function from malicious scripts.

use rhai::{Array, NativeCallContext, EvalAltResult, Position};

// This function builds an array of arbitrary size, but is protected
// against attacks by first checking with the allowed limit set
// into the 'Engine'.
pub fn grow(context: NativeCallContext, size: i64) -> Result<Array, Box<EvalAltResult>>
{
    // Make sure the function does not generate a
    // data structure larger than the allowed limit
    // for the Engine!
    if size as usize > context.engine().max_array_size() {
        return Err(EvalAltResult::ErrorDataTooLarge(
            "Size to grow".to_string(),
            context.engine().max_array_size(),
            size as usize,
            context.position(),
        ).into());
    }

    let array = Array::new();

    for x in 0..size {
        array.push(x.into());
    }

    OK(array)
}

Example – Call a Function Within a Function

The native call context can be used to call a function within the current evaluation via call_fn (or more commonly call_native_fn).

use rhai::{Engine, NativeCallContext};

let mut engine = Engine::new();

// A function expecting a callback in form of a function pointer.
engine.register_fn("super_call", |context: NativeCallContext, value: i64| {
    // Call a function within the current evaluation!
    // 'call_native_fn' ensures that only registered native Rust functions
    // are called, so a scripted function named 'double' cannot hijack
    // the process.
    // To also include scripted functions, use 'call_fn' instead.
    context.call_native_fn::<i64>("double", (value,))
    //                                      ^^^^^^^^ arguments passed in tuple
});

Example – Implement a Callback

The native call context can be used to call a function pointer or closure that has been passed as a parameter to the function (via FnPtr::call_within_context), thereby implementing a callback.

use rhai::{Dynamic, FnPtr, NativeCallContext, EvalAltResult};

pub fn greet(context: NativeCallContext, callback: FnPtr) -> Result<String, Box<EvalAltResult>>
{
    // Call the callback closure with the current evaluation context!
    let name = callback.call_within_context(&context, ())?;
    Ok(format!("hello, {}!", name))
}

Advanced Usage – Recreate NativeCallContext

The NativeCallContext type encapsulates the entire context of a script up to the particular point of the native Rust function call.

The data inside a NativeCallContext can be stored (as a type NativeCallContextStore) for later use, when a new NativeCallContext can be constructed based on these stored data.

A reconstructed NativeCallContext acts almost the same as the original instance, so it is possible to suspend the evaluation of a script, and to continue at a later time with a new NativeCallContext.

Doing so requires the internals feature to access internal API’s.

Step 1: Store NativeCallContext data

// Store context for later use
let context_data = context.store_data();

// ... store 'context_data' somewhere ...
secret_database.push(context_data);

Step 2: Recreate NativeCallContext

// ... do something else ...

// Recreate the context
let context_data = secret_database.get();

let new_context = context_data.create_context(&engine);