Crate rquickjs[−][src]
High-level bindings to quickjs
The rquickjs
crate provides safe high-level bindings to the quickjs javascript engine.
This crate is heavily inspired by the rlua crate.
The Runtime
and Context
objects
The main entry point of this library is the Runtime
struct.
It represents the interperter state and is used to create Context
objects. As the quickjs library does not support threading the runtime is locked behind a
mutex. Multiple threads cannot run as script or create objects from the same runtime at the
same time.
The Context
object represents a global environment. Contexts of the same runtime
can share javascript objects like in browser between frames of the same origin.
Converting Values
This library has multiple traits for converting to and from javascript.
The IntoJs
trait is used for taking rust values and turning them into javascript values.
The FromJs
is for converting javascript value to rust.
Note that this trait does not automatic coercion but the Coerced
can be used to convert
the values with coercion.
For values which represent the name of variables or indecies the
trait IntoAtom
is available to convert values to the represention
quickjs requires.
Optional features
Default
This crate can be customized via features. The following features is enabled by default but can be disabled when not needed:
classes
enables support for ES6 classes. Any user-defined Rust type can be exported to JS as an ES6 class which can be derived and extended by JS.properties
enables support for object properties (Object.defineProperty
).exports
adds an ability to read the module exports.
Advanced
The following features may be enabled to get an extra functionality:
allocator
adds support for custom allocators forRuntime
. The allocators should implementsAllocator
trait and can be plugged onRuntime
creation viaRuntime::new_with_alloc
.rust-alloc
forces using Rust's global allocator by default instead of libc's one.loader
adds support for custom ES6 modules resolvers and loaders. The resolvers and loaders should implementsResolver
andLoader
traits respectively and can be plugged in already existingRuntime
before loading modules viaRuntime::set_loader
. The resolvers and loaders can be easily combined via tuples. When the previous resolver or loader failed the next one will be applied.dyn-load
adds support for loadable native modules (so/dll/dylib).futures
adds support for async Rust. When enabled the Rust futures can be passed to JS as ES6 Promises and ES6 Promises can be given back as Rust futures.tokio
adds integration withtokio
async runtime. The methodRuntime::spawn_executor
can be used withTokio
to spawn async executor.async-std
adds integration withasync_std
runtime. The methodRuntime::spawn_executor
can be used withAsyncStd
to spawn async executor.smol
adds integrations withsmol
async runtime. The methodRuntime::spawn_executor
can be used withSmol
to spawn async executor.macro
enables some useful procedural macros which gets Rust/JS interop much easy. An attribute macros can be applied to functions, constants and modules. An derive macros can be used with structs and enums.
Custom
To gets build faster the numbers of arguments which can be passed to and given by the functions is limited to 6. If you need more arguments you can enabled feature max-args-N
where N is number from 7 to 16.
Extra types
This crate has support for conversion of many Rust types like Option
, Result
, Vec
and other collections. In addition an extra types support can be enabled via features:
either
addsFromJs
/IntoJs
implementations forEither
indexmap
addsFromJs
/IntoJs
implementations forIndexSet
andIndexMap
Bindings
The bindings is pre-built for the following platforms:
i686-unknown-linux-gnu
,x86_64-unknown-linux-gnu
x86_64-apple-darwin
i686-pc-windows-gnu
,x86_64-pc-windows-gnu
,i686-pc-windows-msvc
,x86_64-pc-windows-msvc
To build the crate for unsupported target you must enable bindgen
feature.
Experimental
parallel
enables multithreading support.
Note that the experimental features which may not works as expected. Use it for your own risk.
Debugging
QuickJS can be configured to output some info which can help debug. The following features enables that:
dump-bytecode
dump-gc
dump-gc-free
dump-free
dump-leaks
dump-mem
dump-objects
dump-atoms
dump-shapes
dump-module-resolve
dump-promise
dump-read-object
Modules
intrinsic | A marker types for intrinsic |
qjs | Native low-level bindings |
Macros
class_def | classes The macro to simplify class definition. |
generic_loader | loader The helper macro to impl |
module_init | Helper macro to provide module init function |
Structs
Accessor | properties The accessor descriptor of a readonly property |
Array | Rust representation of a javascript object optimized as an array. |
Async | futures The wrapper for async functons |
AsyncStd | async-std The |
Atom | An atom is value representing the name of a variable of an objects and can be created from any javascript value. |
BuiltinLoader | loader The builtin script module loader |
BuiltinResolver | loader The builtin module resolver |
Bundle | The resolver and loader for bundles of compiled modules |
Class | classes The class object interface |
ClassId | classes The type of identifier of class |
Coerced | The wrapper for values to force coercion |
Compile | loader Modules compiling data |
Constructor | classes The wrapper for constructor function |
Context | A single execution context with its own global variables and stack. |
ContextBuilder | Used for building a |
Created | The marker for the module which is created but not loaded yet |
Ctx | Context in use, passed to |
Evaluated | The marker for the module which is already loaded and evaluated |
Executor | futures The async executor future |
ExportEntriesIter | exports An iterator over the items exported out a module |
ExportNamesIter | exports An iterator over the items exported out a module |
FileResolver | loader The file module resolver |
Filter | The property filter |
Func | The wrapper for function to convert is into JS |
Function | Rust representation of a javascript function. |
Idle | The idle awaiting future |
Loaded | The marker for the module which is loaded but not evaluated yet |
MemoryUsage | |
Method | The wrapper for method functions |
Module | Javascript module with certain exports and imports |
ModuleLoader | loader The builtin native module loader |
MutFn | The wrapper for mutable functions |
Native | The marker for the module which is created using |
NativeLoader | dyn-load The native module loader |
Null | The placeholder which treated as |
Object | Rust representation of a javascript object. |
OnceFn | The wrapper for once functions |
Opt | The wrapper to get optional argument from input |
Persistent | The wrapper for JS values to keep it from GC |
Promise | futures Future-aware promise |
Promised | futures Wrapper for futures to convert to JS promises |
Property | properties The data descriptor of a property |
RefsMarker | classes The helper for QuickJS garbage collector which helps it find internal JS object references. |
RegisteryKey | registery Key for a registery of a context. |
Rest | The wrapper the rest arguments from input |
Runtime | Quickjs runtime, entry point of the library. |
RustAllocator | The allocator which uses Rust global allocator |
Script | The marker for the module which is created from text source |
ScriptLoader | loader The script module loader |
Smol | smol and parallel The |
String | Rust representation of a javascript string. |
Symbol | Rust representation of a javascript symbol. |
This | The wrapper to get |
Tokio | tokio The |
Undefined | The placeholder which treated as |
Uninitialized | The placeholder which treated as uninitialized JS value |
Value | Any javascript value |
WithProto | classes The prototype setting wrapper |
Enums
Error | Error type of the library. |
Type | The type of value |
Traits
Allocator | allocator The allocator interface |
AsArguments | A helper trait to pass arguments on a function calls. |
AsFunction | The trait to wrap rust function to JS directly |
AsProperty | properties The property interface |
ClassDef | classes The ES6 class definition trait |
ExecutorSpawner | futures The trait to spawn execution of pending jobs on async runtime |
FromAtom | Trait for converting values from atoms. |
FromIteratorJs | The Rust's |
FromJs | For converting javascript values to rust values |
HasByteCode | The module data which contains bytecode |
HasRefs | classes The helper trait to mark internal JS value refs |
IntoAtom | Trait for converting values to atoms. |
IntoJs | For converting rust values to javascript values |
Intrinsic | The internal trait to add JS builting |
IteratorJs | |
Loader | loader Module loader interface |
ModuleDef | Module definition trait |
MultiWith | A trait for using multiple contexts at the same time. |
ObjectDef | The helper trait to define objects |
Outlive | The trait to help break lifetime rules when JS objects leaves current context via |
ParallelSend | |
Resolver | loader Module resolver interface |
Type Definitions
ModuleLoadFn | The raw module load function ( |
RawMemPtr | allocator Raw memory pointer |
Result | Result type used throught the library. |
Attribute Macros
bind | An attribute to generate bindings easy |
embed | An attribute to convert scripts modules into builtins |
Derive Macros
FromJs | A macro to derive |
HasRefs | A macro to derive |
IntoJs | A macro to derive |