rusty_v8 0.4.0

Rust bindings to V8
Documentation

Example

use rusty_v8 as v8;

let platform = v8::new_default_platform().unwrap();
v8::V8::initialize_platform(platform);
v8::V8::initialize();

let mut isolate = v8::Isolate::new(Default::default());

let mut handle_scope = v8::HandleScope::new(&mut isolate);
let scope = handle_scope.enter();

let context = v8::Context::new(scope);
let mut context_scope = v8::ContextScope::new(scope, context);
let scope = context_scope.enter();

let code = v8::String::new(scope, "'Hello' + ' World!'").unwrap();
println!("javascript code: {}", code.to_rust_string_lossy(scope));

let mut script = v8::Script::compile(scope, context, code, None).unwrap();
let result = script.run(scope, context).unwrap();
let result = result.to_string(scope).unwrap();
println!("result: {}", result.to_rust_string_lossy(scope));

Design of Scopes

Although the end is in sight, the design is still a bit in flux.

The general idea is that the various scope classes mediate access to the v8 Isolate and the various items on its heap (Local/Global handles, return/escape slots, etc.). At any point in time there exists only one scope object that is directly accessible, which guarantees that all interactions with the Isolate are safe.

A Scope as such is not a trait (there is currently an internal ScopeDefinition trait but that's only there to make implementation easier).

Rather, there are a number of traits that are implemented for the scopes they're applicable to, you've probably seen most of them already. The InIsolate which gives access to &mut Isolate is implemented for all scopes, ToLocal (I might rename that) is implemented for all Scopes in which new Local handles can be created and it sets the appropriate lifetime on them.

Furthermore, many callbacks will receive receive an appropriate Scope object as their first argument, which 'encodes' the the state the isolate is in when the callback is called. E.g. a FunctionCallbackScope implements InIsolate + and ToLocal (it acts as a HandleScope). HostImportModuleDynamicallyScope would also implement InIsolate plus EscapeLocal (it doesn't act like a HandleScope, but it lets you safely escape one MaybeLocal which is returned to the caller).

In a nutshell, that's it.

Open TODOs are:

  • Add these automatic scopes to more callbacks (in progress) and get rid of the necessity to import the MapFnTo trait.
  • Fully integrate TryCatch blocks into the scope system (currently a TryCatch works like a scope internally but it's not integrated).
  • Add methods to some on some of the scopes like get_context() for ContextScope.
  • Rename/reorganize/document.