Crate rusty_v8_m

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.

Re-exports

pub use scope::CallbackScope;

pub use scope::ContextScope;

pub use scope::FunctionCallbackScope;

pub use scope::PropertyCallbackScope;

pub use scope::Scope;

Modules

V8
inspector	Bindings to the V8 Inspector API. Documentation for the V8 inspector API is very sparse, so here are a few references for the next sorry soul who has to dig into it.
json	A JSON Parser and Stringifier.
scope
script_compiler	For compiling scripts.

Structs

AccessorSignature	An AccessorSignature specifies which receivers are valid parameters to an accessor callback.
Allocator	A thread-safe allocator that V8 uses to allocate |ArrayBuffer|'s memory. The allocator is a global V8 setting. It has to be set via Isolate::CreateParams.
Array	An instance of the built-in array constructor (ECMA-262, 15.4.2).
ArrayBuffer	An instance of the built-in ArrayBuffer constructor (ES6 draft 15.13.5).
ArrayBufferView	A base class for an instance of one of "views" over ArrayBuffer, including TypedArrays and DataView (ES6 draft 15.13).
BackingStore	A wrapper around the backing store (i.e. the raw memory) of an array buffer. See a document linked in http://crbug.com/v8/9908 for more information.
BigInt	A JavaScript BigInt value (https://tc39.github.io/proposal-bigint)
BigInt64Array	An instance of BigInt64Array constructor.
BigIntObject	A BigInt object (https://tc39.github.io/proposal-bigint)
BigUint64Array	An instance of BigUint64Array constructor.
Boolean	A primitive boolean value (ECMA-262, 4.3.14). Either the true or false value.
BooleanObject	A Boolean object (ECMA-262, 4.3.15).
Context	A sandboxed execution context with its own set of built-in objects and functions.
CreateParams	Initial configuration parameters for a new Isolate.
Data	The superclass of objects that can reside on V8's heap.
DataView	An instance of DataView constructor (ES6 draft 15.13.7).
Date	An instance of the built-in Date constructor (ECMA-262, 15.9).
EscapableHandleScope	A HandleScope which first allocates a handle in the current scope which will be later filled with the escape value.
Exception	Create new error objects by calling the corresponding error object constructor with the message.
External	A JavaScript value that wraps a C++ void*. This type of value is mainly used to associate C++ data structures with JavaScript objects.
ExternalReferences
FinalizationGroup	An instance of the built-in FinalizationRegistry constructor.
Float32Array	An instance of Float32Array constructor (ES6 draft 15.13.6).
Float64Array	An instance of Float64Array constructor (ES6 draft 15.13.6).
Function	A JavaScript function object (ECMA-262, 15.3).
FunctionCallbackArguments
FunctionCallbackInfo	The argument information given to function call callbacks. This class provides access to information about the context of the call, including the receiver, the number and values of arguments, and the holder of the function.
FunctionTemplate	A FunctionTemplate is used to create functions at runtime. There can only be one function created from a FunctionTemplate in a context. The lifetime of the created function is equal to the lifetime of the context. So in case the embedder needs to create temporary functions that can be collected using Scripts is preferred.
Global	An object reference that is independent of any handle scope. Where a Local handle only lives as long as the HandleScope in which it was allocated, a global handle remains valid until it is explicitly disposed using reset().
HandleScope	A stack-allocated class that governs a number of local handles. After a handle scope has been created, all local handles will be allocated within that handle scope until either the handle scope is deleted or another handle scope is created. If there is already a handle scope and a new one is created, all allocations will take place in the new handle scope until it is deleted. After that, new handles will again be allocated in the original handle scope.
Int8Array	An instance of Int8Array constructor (ES6 draft 15.13.6).
Int16Array	An instance of Int16Array constructor (ES6 draft 15.13.6).
Int32Array	An instance of Int32Array constructor (ES6 draft 15.13.6).
Int32	A JavaScript value representing a 32-bit signed integer.
Integer	A JavaScript value representing a signed integer.
Isolate	Isolate represents an isolated instance of the V8 engine. V8 isolates have completely separate states. Objects from one isolate must not be used in other isolates. The embedder can create multiple isolates and use them in parallel in multiple threads. An isolate can be entered by at most one thread at any given time. The Locker/Unlocker API must be used to synchronize.
IsolateHandle	IsolateHandle is a thread-safe reference to an Isolate. It's main use is to terminate execution of a running isolate from another thread.
Local	An object reference managed by the v8 garbage collector.
Location	A location in JavaScript source.
Map	An instance of the built-in Map constructor (ECMA-262, 6th Edition, 23.1.1).
Message	An error message.
Module	A compiled JavaScript module.
Name	A superclass for symbols and strings.
Number	A JavaScript number value (ECMA-262, 4.3.20)
NumberObject	A Number object (ECMA-262, 4.3.21).
Object	A JavaScript object (ECMA-262, 4.3.3)
ObjectTemplate	An ObjectTemplate is used to create objects at runtime.
OwnedIsolate	Same as Isolate but gets disposed when it goes out of scope.
Platform
Primitive	The superclass of primitive values. See ECMA-262 4.3.2.
PrimitiveArray	An array to hold Primitive values. This is used by the embedder to pass host defined options to the ScriptOptions during compilation.
Private	A private symbol
Promise	An instance of the built-in Promise constructor (ES6 draft).
PromiseRejectMessage
PromiseResolver
PropertyAttribute
PropertyCallbackArguments
PropertyCallbackInfo	The information passed to a property callback about the context of the property access.
Proxy	An instance of the built-in Proxy constructor (ECMA-262, 6th Edition, 26.2.1).
RegExp	An instance of the built-in RegExp constructor (ECMA-262, 15.10).
ReturnValue
Script	A compiled JavaScript script, tied to a Context which was active when the script was compiled.
ScriptOrModule	A container type that holds relevant metadata for module loading.
ScriptOrigin	The origin, within a file, of a script.
Set	An instance of the built-in Set constructor (ECMA-262, 6th Edition, 23.2.1).
SharedArrayBuffer	An instance of the built-in SharedArrayBuffer constructor.
SharedPtr	Wrapper around a C++ shared_ptr. A shared_ptr may be be null.
SharedRef	Wrapper around a C++ shared_ptr. The shared_ptr is assumed to contain a value and may not be null.
Signature	A Signature specifies which receiver is valid for a function.
SnapshotCreator	Helper class to create a snapshot data blob.
StackFrame	A single JavaScript stack frame.
StackTrace	Representation of a JavaScript stack trace. The information collected is a snapshot of the execution stack and the information remains valid after execution continues.
StartupData
String	A JavaScript string value (ECMA-262, 4.3.17).
StringObject	A String object (ECMA-262, 4.3.18).
Symbol	A JavaScript symbol (ECMA-262 edition 6)
SymbolObject	A Symbol object (ECMA-262 edition 6).
Task
TaskBase
Template	The superclass of object and function templates.
TryCatch	An external exception handler.
TryCatchScope	A scope object that will, when entered, active the embedded TryCatch block.
TryFromTypeError
TypedArray	A base class for an instance of TypedArray series of constructors (ES6 draft 15.13.6).
Uint8Array	An instance of Uint8Array constructor (ES6 draft 15.13.6).
Uint8ClampedArray	An instance of Uint8ClampedArray constructor (ES6 draft 15.13.6).
Uint16Array	An instance of Uint16Array constructor (ES6 draft 15.13.6).
Uint32Array	An instance of Uint32Array constructor (ES6 draft 15.13.6).
Uint32	A JavaScript value representing a 32-bit unsigned integer.
UnboundModuleScript	A compiled JavaScript module, not yet tied to a Context.
UnboundScript	A compiled JavaScript script, not yet tied to a Context.
UniquePtr	Pointer to object allocated on the C++ heap. The pointer may be null.
UniqueRef	Pointer to object allocated on the C++ heap. The pointer may not be null.
Value	The superclass of all JavaScript values and objects.
WasmModuleObject

Enums

FunctionCodeHandling
ModuleStatus	The different states a module can be in.
NewStringType
PromiseRejectEvent
PromiseState

Constants

DONT_DELETE	Not configurable. Corresponds to Object.defineProperty(o, "p", { configurable: false }).
DONT_ENUM	Not enumerable. Corresponds to Object.defineProperty(o, "p", { enumerable: false }).
NONE	No property attributes.
READ_ONLY	Not writable. Corresponds to Object.defineProperty(o, "p", { writable: false }).

Traits

EscapeLocal
InIsolate	Trait for retrieving the current isolate from a scope object.
MapFnTo
TaskImpl
ToLocal	When scope implements this trait, this means that Local handles can be created inside it.
ToLocalOrReturnsLocal

Functions

backing_store_deleter_callback⚠
new_default_allocator	malloc/free based convenience allocator.
new_default_platform
null
undefined

Type Definitions

AccessorNameGetterCallback	AccessorNameGetterCallback is used as callback functions when getting a particular property. See Object and ObjectTemplate's method SetAccessor.
BackingStoreDeleterCallback
FunctionCallback
HostImportModuleDynamicallyCallback	HostImportModuleDynamicallyCallback is called when we require the embedder to load a module. This is used as part of the dynamic import syntax.
HostInitializeImportMetaObjectCallback	HostInitializeImportMetaObjectCallback is called the first time import.meta is accessed for a module. Subsequent access will reuse the same value.
MessageCallback
PromiseRejectCallback
ResolveCallback	Called during Module::instantiate_module. Provided with arguments: (context, specifier, referrer). Return None on error.

Unions

ExternalReference