Module enif_protobuf

Description
Function Index
Function Details

Fast Google Protobuf (proto2/proto3) encoder and decoder for Erlang/OTP, written in C as a NIF.

Description

Fast Google Protobuf (proto2/proto3) encoder and decoder for Erlang/OTP, written in C as a NIF.

Drop-in replacement for the encode_msg/1 and decode_msg/2 functions that gpb generates from .proto files: same record tuples, same wire format, byte-identical output, no libprotobuf or protoc dependency.

Load a schema once with load_cache/1, then call encode/1 and decode/2:

  ok = enif_protobuf:load_cache(x:get_msg_defs()),
  Bin = enif_protobuf:encode(#'Person'{name = "abc", id = 345}),
  #'Person'{} = enif_protobuf:decode(Bin, 'Person').

The schema cache is global to the BEAM node and shared by all processes; encode and decode take a read lock and are safe to call concurrently. Calls run on normal schedulers and are not dirty NIFs.

Only {string_as_list, boolean()} and {with_utf8, boolean()} options exist, see set_opts/1.

Function Index

debug_term/1	Print the internal node layout of a loaded schema entry.
decode/2	Decode binary protobuf wire format into a message record or map tuple.
decode_msg/3	`load_cache/1` followed by `decode/2`, for call sites where loading the schema on every call is acceptable.
encode/1	Encode a message.
encode_msg/2	`load_cache/1` followed by `encode/1`, for call sites where loading the schema on every call is acceptable.
load_cache/1	Load a schema, replacing any schema loaded before.
purge_cache/0	Free the loaded schema.
set_opts/1	Set encoder/decoder options.

Function Details

debug_term/1

debug_term(Term::term()) -> term()

Print the internal node layout of a loaded schema entry. Debugging aid that returns its argument unchanged.

decode/2

decode(Binary::binary(), Name::atom()) -> tuple()

Decode binary protobuf wire format into a message record or map tuple. Name is the message atom as written in the .proto file, e.g. `Person''.

Raises unknown_msg when the loaded schema has no message called Name, cache_not_exists when no schema is loaded, and badarg on malformed wire data.

decode_msg/3

decode_msg(Bin::binary(), Name::atom(), Defs::list()) -> tuple()

load_cache/1 followed by decode/2, for call sites where loading the schema on every call is acceptable.

encode/1

encode(Tuple::tuple()) -> binary()

Encode a message. Msg is a gpb record (or a map tuple from a -maps generated module) that matches a message in the loaded schema; the result is protobuf wire format.

Raises badarg if Msg is not a tuple or does not match the schema, and cache_not_exists if no schema is loaded.

encode_msg/2

encode_msg(Msg::tuple(), Defs::list()) -> binary()

load_cache/1 followed by encode/1, for call sites where loading the schema on every call is acceptable.

load_cache/1

load_cache(List::list()) -> ok

Load a schema, replacing any schema loaded before. Defs is exactly what a gpb generated module returns from Module:get_msg_defs().

The cache is global to the node, so all processes and applications on one VM share it; two applications with different schemas need separate nodes or one coordinated load_cache/1 call.

purge_cache/0

purge_cache() -> ok

Free the loaded schema. Later calls to encode/1 or decode/2 raise cache_not_exists until load_cache/1 is called again.

set_opts/1

set_opts(Opts::[{string_as_list, boolean()} | {with_utf8, boolean()}]) -> ok

Set encoder/decoder options. Call before load_cache/1; the options apply to the schema loaded afterwards.

{string_as_list, true} makes string fields decode to lists instead of binaries (default false). {with_utf8, true} allows non-Latin-1 UTF-8 in string fields when encoding (default false).

Raises badarg for unknown options, non-boolean values or an improper list.

Generated by EDoc