Attribute Macro deno_core::op2

#[op2]

A macro designed to provide an extremely fast V8->Rust interface layer.

op2

#[op2] is the in-progress replacement for #[op].

Strings

Strings in Rust are always UTF-8. Strings in v8, however, are either two-byte UTF-16 or one-byte Latin-1. One-byte Latin-1 strings are not byte-compatible with UTF-8, as characters with the index 128-255 require two bytes to encode in UTF-8.

Because of this, Strings in ops always require a copy (at least) to ensure that we are not incorrectly passing Latin-1 data to methods that expect a UTF-8 string. At this time there is no way to avoid this copy, though the op code does attempt to avoid any allocations where possible by making use of a stack buffer.

async calls

Asynchronous calls are supported in two forms:

async fn op_xyz(/* ... */) -> X {}

and

fn op_xyz(/* ... */) -> impl Future<Output = X> {}

These are desugared to a function that adds a hidden promise_id argument, and returns Option<X> instead. Deno will eagerly poll the op, and if it is immediately ready, the function will return Some(X). If the op is not ready, the function will return None and the future will be handled by Deno’s pending op system.

fn op_xyz(promise_id: i32, /* ... */) -> Option<X> {}

Parameters

Rust	Fastcall	v8
bool	✅	Bool
i8	✅	Uint32, Int32, Number, BigInt
u8	✅	Uint32, Int32, Number, BigInt
i16	✅	Uint32, Int32, Number, BigInt
u16	✅	Uint32, Int32, Number, BigInt
i32	✅	Uint32, Int32, Number, BigInt
u32	✅	Uint32, Int32, Number, BigInt
#[smi] ResourceId	✅	Uint32, Int32, Number, BigInt	SMI is internally represented as a signed integer, but unsigned `#[smi]` types will be bit-converted to unsigned values for the Rust call. JavaScript code will continue to see signed integers.
#[bigint] i64	✅	Uint32, Int32, Number, BigInt
#[bigint] u64	✅	Uint32, Int32, Number, BigInt
#[bigint] isize	✅	Uint32, Int32, Number, BigInt
#[bigint] usize	✅	Uint32, Int32, Number, BigInt
f32	✅	Uint32, Int32, Number, BigInt
f64	✅	Uint32, Int32, Number, BigInt
#[string] String	✅	String	Fastcall available only if string is Latin-1. Will always create an allocated, UTF-8 copy of the String data.
#[string] &str	✅	String	Fastcall available only if string is Latin-1. Will create an owned `String` copy of the String data if it doesn't fit on the stack. Will never allocate in a fastcall, but will copy Latin-1 -> UTF-8.
#[string] Cow<str>	✅	String	Fastcall available only if string is Latin-1. Will create a `Cow::Owned` copy of the String data if it doesn't fit on the stack. Will always be `Cow::Borrowed` in a fastcall, but will copy Latin-1 -> UTF-8.
#[string(onebyte)] Cow<[u8]>	✅	String	Fastest `String`-type method. If the string is not Latin-1, will throw a TypeError.
&v8::Value	✅	any
&v8::String	✅	String
&v8::Object	✅	Object
&v8::Function	✅	Function
&v8::...	✅	...
v8::Local<v8::Value>	✅	any
v8::Local<v8::String>	✅	String
v8::Local<v8::Object>	✅	Object
v8::Local<v8::Function>	✅	Function
v8::Local<v8::...>	✅	...
#[global] v8::Global<v8::Value>		any	⚠️ Slower than `v8::Local`.
#[global] v8::Global<v8::String>		String	⚠️ Slower than `v8::Local`.
#[global] v8::Global<v8::Object>		Object	⚠️ Slower than `v8::Local`.
#[global] v8::Global<v8::Function>		Function	⚠️ Slower than `v8::Local`.
#[global] v8::Global<v8::...>		...	⚠️ Slower than `v8::Local`.
#[serde] SerdeType		any	⚠️ May be slow.
#[serde] (Tuple, Tuple)		any	⚠️ May be slow.
#[buffer] &mut [u8]	✅	UInt8Array (resizable=true,false)	⚠️ JS may modify the contents of the slice if V8 is called re-entrantly.
#[buffer] &[u8]	✅	UInt8Array (resizable=true,false)	⚠️ JS may modify the contents of the slice if V8 is called re-entrantly.
#[buffer(copy)] Vec<u8>	✅	UInt8Array (resizable=true,false)	Safe, but forces a copy.
#[buffer(copy)] Box<[u8]>	✅	UInt8Array (resizable=true,false)	Safe, but forces a copy.
#[buffer(copy)] bytes::Bytes	✅	UInt8Array (resizable=true,false)	Safe, but forces a copy.
#[buffer] &mut [u32]	✅	UInt32Array (resizable=true,false)	⚠️ JS may modify the contents of the slice if V8 is called re-entrantly.
#[buffer] &[u32]	✅	UInt32Array (resizable=true,false)	⚠️ JS may modify the contents of the slice if V8 is called re-entrantly.
#[buffer(copy)] Vec<u32>	✅	UInt32Array (resizable=true,false)	Safe, but forces a copy.
#[buffer(copy)] Box<[u32]>	✅	UInt32Array (resizable=true,false)	Safe, but forces a copy.
#[buffer] JsBuffer		ArrayBuffer, ArrayBufferView (resizable=false)	⚠️ JS may modify the contents of slices obtained from buffer.
#[buffer(detach)] JsBuffer		ArrayBuffer, ArrayBufferView (resizable=true,false)	Safe.
*const std::ffi::c_void	✅	External
*mut std::ffi::c_void	✅	External
&OpState	✅
&mut OpState	✅
Rc<RefCell<OpState>>	✅
#[state] &StateObject	✅		Extracts an object from `OpState`.
#[state] &mut StateObject	✅		Extracts an object from `OpState`.
&JsRuntimeState	✅		Only usable in `deno_core`.
&mut JsRuntimeState	✅		Only usable in `deno_core`.
Rc<RefCell<JsRuntimeState>>	✅		Only usable in `deno_core`.

Return Values

Rust	Fastcall	Async	v8
bool	✅
i8	✅
u8	✅
i16	✅
u16	✅
i32	✅
u32	✅
#[smi] ResourceId	✅		SMI is internally represented as a signed integer, but unsigned `#[smi]` types will be bit-converted to unsigned values for the Rust call. JavaScript code will continue to see signed integers.
#[bigint] i64
#[bigint] u64
#[bigint] isize
#[bigint] usize
#[number] i64	✅		Result must fit within `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`
#[number] u64	✅		Result must fit within `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`
#[number] isize	✅		Result must fit within `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`
#[number] usize	✅		Result must fit within `Number.MIN_SAFE_INTEGER` and `Number.MAX_SAFE_INTEGER`
f32	✅
f64	✅
#[string] String
#[string] &str
#[string] Cow<str>
#[string(onebyte)] Cow<[u8]>
#[buffer] V8Slice<u8>
#[buffer] Vec<u8>
#[buffer] Box<[u8]>
#[buffer] bytes::BytesMut
#[buffer] V8Slice<u32>
*const std::ffi::c_void	✅
*mut std::ffi::c_void	✅
v8::Local<v8::Value>
v8::Local<v8::String>
v8::Local<v8::Object>
v8::Local<v8::Function>
v8::Local<v8::...>
#[global] v8::Global<v8::Value>
#[global] v8::Global<v8::String>
#[global] v8::Global<v8::Object>
#[global] v8::Global<v8::Function>
#[global] v8::Global<v8::...>
#[serde] SerdeType
#[serde] (Tuple, Tuple)