@spec binary_to_slice(erl_nif_binary) :: []u8

converts a e.ErlNifBinary to []const u8.

Does not perform allocations or copies

binary data

This points to the data location of the binary, which might either be in the shared binary heap, or it might be in the process heap (for small binaries). This should be considered read-only, attempts to sneakily modify these data will have undefined effects, possibly including broken comparison operations.

@spec binary_to_term(env, []u8) :: !term

converts a []u8 to a term/0. The binary must be encoded using erlang term format.

This is a thin wrapper over e.enif_binary_to_term.

@spec cleanup(anytype, anytype) :: void

generic cleanup function that can be used to cleanup values that have been created by get.

The second parameter is an options parameters, which should be passed a struct (possibly anonymous) with the following fields:

• allocator: which allocator should be used to clean up allocations. optional, defaults to the threadlocal allocator value

@spec compare(term, term) :: beam.Compared

compares two terms.

@spec get(T, beam.env, beam.term, anytype) :: T

converts BEAM term dynamic types into static zig types

The arguments are as follows:

1. destination type
2. environment
3. term to convert
4. struct (usually passed as anonymous) of keyword options for additional features. See supported options

See also make for the reverse operation.

The following type classes (as passed as 1st argument) are supported by get:

integer

• unsigned and signed integers supported
• all integer sizes from 0..64 bits supported (including non-power-of-2 sizes)
• for sizes bigger than 64, supported, but the passed term must be a native-endian binary.

Example

do_get(47)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x: i32 = beam.get(i32, env, term, .{});  // -> x = 47
     ...
}

enum

• may be passed the integer value of the enum.
• may be passed the atom representation of the enum.
• zero- and one- item enum types are not currently supported

Example

do_get(:foo)

const EnumType = enum {foo, bar};
pub fn do_get(env: beam.env, term: beam.term) void {
     const x: EnumType = beam.get(EnumType, env, term, .{});  // -> x = .foo
     ...
}

float

• supports f16, f32, and f64 types.
• may be passed a BEAM float/0 term
• atoms :infinity, :neg_infinity, :NaN are also supported

Example

do_get(47.0)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x: f32 = beam.get(f32, env, term, .{});  // -> x = 47.0
     ...
}

struct

• may be passed map/0 with atom/0 keys and values of the appropriate type
• may be passed a keyword/0 list with atom/0 keys and values of the appropriate type.
• inner values are recursively converted to the appropriate type.
• NOTE: the struct types must be exported as pub in the module's top-level namespace.
• if the struct is packed or extern, supports binary data.

Example

do_get(%{foo: 47, bar: %{baz: :quux}})

pub const EnumType = enum {quux, mlem};

pub const InnerType = struct {
   baz: EnumType,
};

pub const StructType = struct {
   foo: i32,
   bar: InnerType
};

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get(StructType, env, term, .{});  // -> x = .{foo: 47, bar: .{baz: .quux}}
     ...
}

bool

• supports true and false boolean/0 terms only.

Example

do_get(true)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x: bool = beam.get(bool, env, term, .{});  // -> x = true
     ...
}

array

• supports lists of terms that can be converted to the array's element type.
• note that arrays have compile-time known length.
• if the array's element is integers, floats, packed or extern structs, or arrays that support binaries, then the array can be passed binary data.
• does not perform allocation

  Allocation warning

  as allocation is not performed, getting could be a very expensive operation.

Example

do_get([47, 48, 49])
do_get(<<47 :: signed-int-size(32), 48 :: signed-int-size(32), 49 :: signed-int-size(32)>>)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get([3]i32, env, term, .{});  // -> x = .{47, 48, 49}
     ...
}

single-item pointer

• allocates memory based on allocator provided in the options, otherwise defaults to beam.allocator
• supports any type as above.
• returns an error if the allocation fails.

Example

do_get(%{foo: 47})

const MyStruct = struct { foo: i32 };

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get(*MyStruct, env, term, .{});  // -> x = a pointer to .{.foo = 47}
     ...
}

slice

• allocates memory based on allocator provided in the options, otherwise defaults to beam.allocator
• note that slice carries a runtime length
• supports list of any type
• supports binary of any type that can be represented as a fixed size binary.

Example

do_get([47, 48, 49])
do_get(<<47 :: signed-int-size(32), 48 :: signed-int-size(32), 49 :: signed-int-size(32)>>)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get([]i32, env, term, .{});  // -> x = a pointer to .{47, 48, 49}
     ...
}

many-item-pointer

• allocates memory based on allocator provided in the options, otherwise defaults to beam.allocator

• supports list of any type

• supports binary of any type that can be represented as a fixed size binary.

• the runtime length is not a part of this datastructure, you are expected to keep track of it using some other mechanism

  Length warning

  due to the fact that this datatype drops its length information, this datatype should be handled with extreme care.

Example

do_get([47, 48, 49])
do_get(<<47 :: signed-int-size(32), 48 :: signed-int-size(32), 49 :: signed-int-size(32)>>)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get([*]i32, env, term, .{});  // -> x = a pointer to .{47, 48, 49}
     ...
}

cpointer

• allocates memory based on allocator provided in the options, otherwise defaults to beam.allocator

• supports list of any type

• supports binary of any type that can be represented as a fixed size binary.

• the runtime length is not a part of this datastructure, you are expected to keep track of it using some other mechanism

  Length warning

  due to the fact that this datatype drops its length information, this datatype should only be used where c interop is needed

Example

do_get([47, 48, 49])
do_get(<<47 :: signed-int-size(32), 48 :: signed-int-size(32), 49 :: signed-int-size(32)>>)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get([*]i32, env, term, .{});  // -> x = a pointer to .{47, 48, 49}
     ...
}

optional

• accepts atom/0 nil as well as whatever the child type is.
• note that zig has null so nil will get converted to null.

Example

do_get(nil)

pub fn do_get(env: beam.env, term: beam.term) void {
     const x = beam.get(?i32, env, term, .{});  // -> x = null
     ...
}

Supported options

• allocator: the allocator to use for allocations. If not provided, defaults to beam.allocator.
• error_info: pointer to a term that can be populated with error information that gets propagated on failure to convert. If omitted, the code to produce these errors will get optimized out.

@spec make(env, anytype, anytype) :: term

converts static zig types into BEAM term dynamic types

The arguments are as follows:

• environment
• value to convert to term
• options struct (usually passed as anonymous) of keyword options for additional features. See supported options. Note this struct must be comptime-known.

See also get for the reverse operation.

The following zig types are supported:

term

• no conversion is performed
• this type is necessary for recursive make operations

void

• returns atom :ok
• supporting this type makes metaprogramming easier.

pid

• convrted into a term representing pid/0

std.builtin.StackTrace

• special interface for returning stacktrace info to BEAM.

integers

• unsigned and signed integers supported
• all integer sizes from 0..64 bits supported (including non-power-of-2 sizes)
• returns a BEAM integer/0 term
• for sizes bigger than 64, supported, but the passed term will be converted into a binary term bearing the integer encoded with native endianness.
• comptime integers supported

Example

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, 47, .{});
}

do_make() # -> 47

floats

• supports f16, f32, and f64 types.
• supports comptime float type.
• returns a BEAM float/0 term
• may also return one of the atom/0 type :infinity, :neg_infinity, :NaN

Example

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, 47.0, .{});
}

do_make() # -> 47.0

bool

• supports bool types.
• returns a BEAM boolean/0 term

Example

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, true, .{});
}

do_make() # -> true

enum or error enum

• supports enum or error types.
• doesn't support zero or one-item enums.
• returns a BEAM atom/0 term
• also supports enum literals.

Example

with an enum:

const EnumType = enum {foo, bar};

pub fn do_make(env: beam.env) beam.term {
   const e = EnumType.foo;
   return beam.make(env, e, .{});
}

with an error enum:

const ErrorType = error {foo, bar};

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, error.foo, .{});
}

with an enum literal:

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, .foo, .{});
}

do_make() # -> :foo

Enum literals

Enum literals are especially useful for returning atoms, such as :ok or :error. Note that error is a reserved word in zig, so you will need to use .@"error" to generate the corresponding atom.

optionals or null

• supports any child type supported by make
• returns the atom/0 type nil or the child type

Example

with null literal:

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, null, .{});
}

with an optional type:

pub fn do_make(env: beam.env) beam.term {
   const value: ?i32 = null;
   return beam.make(env, value, .{});
}

do_make() # -> null

arrays

• supports arrays of any term that can be encoded using make
• note that arrays have compile-time known length.
• outputs as a list of the encoded terms
• arrays of u8 default to outputting binary, this is the only exception to the above rule.
• if the array's element is integers, floats, packed or extern structs, or arrays that support binaries, then the array can be output as binary data, by setting output_type option to .binary
• if the array's element is u8 and you would prefer outputting as a list, setting output_type option to .list will do this.

Examples

array, u8, output as binary/0:

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, "foo", .{});
}

do_make() # -> "foo"

array, u8, output as list/0:

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, "foo", .{.output_type = .list});
}

do_make() # -> ~C'foo'

array, u16, output as list/0:

pub fn do_make(env: beam.env) beam.term {
   const list = [_]u16{47, 48, 49}
   return beam.make(env, list, .{});
}

do_make() # -> [47, 48, 49]

array, u16, output as binary/0:

pub fn do_make(env: beam.env) beam.term {
   const list = [_]u16{47, 48, 49}
   return beam.make(env, list, .{.output_type = .binary});
}

do_make() # -> <<47, 00, 48, 00, 49, 00>>

structs

• supports structs with fields of any term that can be encoded using make
• outputs as a map/0 with atom keys and the encoded terms as values
• for packed or extern structs, supports binary data by setting output_type option to .binary
• encoding options are passed recursively, if something more complex is needed, encoding should be performed manually.
• supports anonymous structs

Examples

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, .{.foo = 123, .bar = "bar", .baz = .baz}, .{});
}

do_make() # -> %{foo: 123, bar: "bar", baz: :baz}

tuples

• supports tuples with any term that can be encoded using make
• outputs as a tuple/0.
• encoding options are passed recursively, if something more complex is needed, encoding should be performed manually.
• note that error atom should be encoded as .@"error"

Examples

pub fn do_make(env: beam.env) beam.term {
   return beam.make(env, .{.ok, "foo", 47}, .{});
}

do_make() # -> {:ok, "foo", 47}

single-item-pointer

• these pointers are only supported for arrays and structs
• these are only supported because they are assumed to be pointers to mutable data
• content will be dereferenced and encoded as if it were the child type
• output_type rules (see arrays) apply.

Examples

pub fn do_make(env: beam.env) beam.term {
   const array = [_]i32{47, 48, 49}
   return beam.make(env, &array, .{});
}

do_make() # -> [47, 48, 49]

slice

• supports arrays of any term that can be encoded using make
• note that arrays have compile-time known length.
• outputs as a list of the encoded terms
• slices of u8 default to outputting binary, this is the only exception to the above rule.
• if the slice's element is integers, floats, packed or extern structs, or arrays that support binaries, then the slice can be output as binary data, by setting output_type option to .binary
• output_type rules (see arrays) apply.

Examples

pub fn do_make(env: beam.env) beam.term {
   const slice = [_]i32{47, 48, 49}[0..]; // note this is now a slice
   return beam.make(env, &slice, .{});
}

do_make() # -> [47, 48, 49]

many-item-pointer

• only supported if the pointer is sentinel-terminated.
• outputs as a list of the encoded terms
• pointers of u8 default to outputting binary, this is the only exception to the above rule.
• if the pointers's element is integers, floats, packed or extern structs, or arrays that support binaries, then the slice can be output as binary data, by setting output_type option to .binary
• output_type rules (see arrays) apply.

Examples

pub fn do_make(env: beam.env) beam.term {
   const slice = [_]i32{47, 48, 49, 0}[0..];
   const ptr = @ptrCast([*:0], &slice.ptr);
   return beam.make(env, &slice, .{});
}

do_make() # -> [47, 48, 49]

cpointer

• only supported if the pointer has child type u8 or pointer.
• in the case of u8 interprets it as [*:0]u8.
• in the case of Pointer interprets it as [*:null]?Pointer.
• no other types are supported.
• note that the content will be interpreted as the pointer type, so rules on pointers (see single-item-pointers))
• output_type rules (see arrays) apply.

Examples

pub fn do_make(env: beam.env) beam.term {
   const slice = [_]i32{47, 48, 49, 0}[0..];
   const ptr = @ptrCast([*:0], &slice.ptr);
   return beam.make(env, &slice, .{});
}

do_make() # -> [47, 48, 49]

@spec make_empty_list(env) :: term

returns the empty list term [].

This is a thin wrapper over e.enif_make_empty_list.

@spec make_error_atom(env) :: term

shortcut for make(env, .@"error", .{})

@spec make_error_pair(env, anytype, anytype) :: term

shortcut for make(env, .{.@"error", value}, options)

@spec make_into_atom(env, []const u8) :: term

turns a []const u8 into a the corresponding atom/0 term.

returns a raised ArgumentError if the length of the string exceeds the vm atom size limit (255 bytes)

This is a thin wrapper over e.enif_make_atom_len.

@spec make_list_cell(env, term, term) :: term

performs a list cons operation for head and tail variables

This is a thin wrapper over e.enif_make_list_cell.

@spec make_pid(env, pid) :: term

turns a e.ErlNifPid into a pid/0 term.

This is a thin wrapper over e.enif_make_pid.

@spec make_ref(env) :: term

causes the VM to generate a new reference term equivalent to Kernel.make_ref/0

This is a thin wrapper over e.enif_make_ref.

@spec make_stacktrace(env, stacktrace) :: term

converts a zig std.builtin.StackTrace into a special term that is designed to be translated and concatenated onto a BEAM stacktrace.

Example term:

[
   %{
     line_info: %{file_name: "/path/to/project/lib/my_app/.Elixir.MyApp.MyModule.zig", line: 15},
     symbol_name: "my_fun",
     compile_unit_name: "Elixir.MyApp.MyModule"
   }
   ...
]

@spec release_binary(erl_nif_binary_pointer) :: void

marks a e.ErlNifBinary as qualified to be garbage collected. This is a thin wrapper over e.enif_release_binary.

@spec self(env) :: !pid

returns a pid value that represents the current or parent process.

equivalent to Kernel.self/0

scope

This function succeeds in all contexts, except for callback contexts. For threaded processes, it will return the process that spawned the thread, whether or not that process is still alive.

@spec send(env, pid, anytype) :: !term

sends data (as a term) to a target process' mailbox.

equivalent to Kernel.send/2

This function is a context-aware wrapper over e.enif_send. that also serializes the message term using make

send from raw nifs or out of bounds callbacks

This function has undefined behaviour when called from raw nifs or callbacks that are out of bounds (e.g. if a new thread is started from a posix call that is not managed by zigler)

in these cases, use e.enif_send directly instead. Note you may have to create the beam.term from an environment first.

@spec term_to_binary(env, term) :: !erl_nif_binary

converts a term/0 to a e.ErlNifBinary using erlang term format serialization.

This is a thin wrapper over e.enif_term_to_binary.

returns error.OutOfMemory if the allocation fails.