external_term.h

Include dependency graph for external_term.h:

This graph shows which files directly or indirectly include external_term.h:

External term deserialization functions.

This header provides external term deserialization functions.

Defines

EXTERNAL_TERM_TAG 131

Enums

enum external_term_write_result_t

Result of an external term write operation.

Returned by serialize and compute-size functions to indicate whether the operation succeeded.

Values:

enumerator ExternalTermWriteOk

enum external_term_read_result_t

Result of an external term read operation.

Returned by validate and deserialize functions to indicate whether the operation succeeded or the input was malformed.

Values:

enumerator ExternalTermReadOk

enumerator ExternalTermReadInvalid

enum external_term_read_opts_t

Options for external term read operations.

Passed to validate and deserialize functions to control their behavior. Reserved for future use; pass ExternalTermReadNoOpts for now.

Values:

enumerator ExternalTermReadNoOpts

Functions

external_term_read_result_t external_term_validate_buf_raw(const void *buf, size_t buf_size, external_term_read_opts_t opts, size_t *required_heap, size_t *bytes_read, GlobalContext *glb)

Validate a raw external term buffer (tag byte excluded).

Like external_term_validate_buf() but expects a buffer without the leading EXTERNAL_TERM_TAG byte. bytes_read does not account for the tag byte.

See also

external_term_validate_buf() for the standard tag-included variant.

external_term_read_result_t external_term_deserialize_buf_raw(const void *buf, size_t buf_size, external_term_read_opts_t opts, Heap *heap, term *out_term, GlobalContext *glb)

Deserialize a raw external term buffer (tag byte excluded) into a term.

Like external_term_deserialize_buf() but expects a buffer without the leading EXTERNAL_TERM_TAG byte.

See also

external_term_deserialize_buf() for the standard tag-included variant.

Warning

external_term_validate_buf_raw() MUST be called successfully on the same buffer before calling this function, and the heap must have been grown to accommodate at least the number of words reported by that call. Skipping validation or providing insufficient heap space results in undefined behavior.

static inline external_term_read_result_t external_term_validate_buf(const void *buf, size_t buf_size, external_term_read_opts_t opts, size_t *required_heap, size_t *bytes_read, GlobalContext *glb)

Validate an external term buffer and compute required heap size.

Verifies that buf contains a well-formed Erlang external term, starting with EXTERNAL_TERM_TAG. On success, required_heap holds the number of heap words needed by external_term_deserialize_buf() and bytes_read holds the total number of bytes consumed (including the tag byte).

See also

external_term_deserialize_buf() to deserialize after a successful validation

See also

external_term_validate_buf_raw() for the tag-excluded variant

Warning

This function MUST be called and must return ExternalTermReadOk before calling external_term_deserialize_buf() on the same buffer. Calling the deserialize function on an unvalidated or invalid buffer results in undefined behavior.

Parameters:

• buf – buffer holding the external term, including the leading EXTERNAL_TERM_TAG byte

• buf_size – size of buf in bytes

• opts – options for the read operation; pass ExternalTermReadNoOpts

• required_heap – [out] number of heap words needed to deserialize the term

• bytes_read – [out] total number of bytes consumed from buf

• glb – the global context

Returns:

ExternalTermReadOk on success, ExternalTermReadInvalid if the buffer does not contain a valid external term

static inline external_term_read_result_t external_term_deserialize_buf(const void *buf, size_t buf_size, external_term_read_opts_t opts, Heap *heap, term *out_term, GlobalContext *glb)

Deserialize an external term buffer into a term.

Instantiates the Erlang external term stored in buf, allocating storage from heap. buf must start with the EXTERNAL_TERM_TAG byte.

See also

external_term_validate_buf() which MUST be called before this function

See also

external_term_deserialize_buf_raw() for the tag-excluded variant

Warning

external_term_validate_buf() MUST be called successfully on the same buffer before calling this function, and the heap must have been grown to accommodate at least the number of words reported by that call. Skipping validation or providing insufficient heap space results in undefined behavior.

Parameters:

• buf – buffer holding the external term, including the leading EXTERNAL_TERM_TAG byte

• buf_size – size of buf in bytes

• opts – options for the read operation; pass ExternalTermReadNoOpts

• heap – [inout] heap from which term storage is allocated

• out_term – [out] the deserialized term (undefined on error)

• glb – the global context

Returns:

ExternalTermReadOk on success, ExternalTermReadInvalid on failure

term external_term_from_binary_with_roots(Context *ctx, size_t binary_ix, size_t offset, size_t *bytes_read, size_t num_roots, term *roots)

Create a term from a binary.

Deserialize a binary term that stores term data in Erlang external term format, and instantiate the serialized terms. The heap from the context will be used to allocate the instantiated terms. This function is the complement of external_term_to_binary. WARNING: This function may call the GC, which may render the input binary invalid.

Parameters:

• ctx – the context that owns the memory that will be allocated.

• binary_ix – offset of the binary in roots

• offset – offset in the binary

• bytes_read – the number of bytes read from the input binary.

• num_roots – number of roots to preserve in case of GC

• roots – roots to preserve in case of GC

Returns:

the term deserialized from the input term, or an invalid term, if deserialization fails.

term external_term_from_const_literal(const void *external_term, size_t size, Context *ctx)

Gets a term from a const literal (module in flash).

Deserialize an external term from external format and returns a term. Use a heap fragment to store the generated terms. The heap fragment is appended to the context heap. Atoms and binaries are not copied.

Parameters:

• external_term – the const literal buffer that will be deserialized

• size – to allocate for term.

• ctx – the context that owns the memory that will be allocated.

Returns:

a term.

term external_term_to_binary(Context *ctx, term t)

Create a binary from a term.

Serialize a term in Erlang external term format, and store the result in a binary term. The heap from the context will be used to allocate the hydrated terms. WARNING: This function may call the GC, which may render the input binary invalid.

Parameters:

• ctx – the context that owns the memory that will be allocated.

• t – the term to return as binary.

Returns:

the term deserialized from the input term, or an invalid term, if deserialization fails.

external_term_write_result_t external_term_compute_external_size_raw(term t, size_t *size, GlobalContext *glb)

Computes the size required for a external term (tag excluded)

This function should be called in order to calculate the required buffer size to store a serialized term in external term format. This function doesn’t prepend the external term 1 byte tag.

Parameters:

• t – the term for which size is calculated

• size – the required buffer size (tag excluded)

• glb – the global context

Returns:

ExternalTermWriteOk in case of success

external_term_write_result_t external_term_serialize_term_raw(term t, void *buf, GlobalContext *glb)

Serialize a term (tag excluded)

This function serializes in external term format given term, and writes it to the given buffer. This function doesn’t prepend the external term 1 byte tag.

Parameters:

• t – the term that will be serialized

• buf – the buffer where the external term is written

• glb – the global context

Returns:

ExternalTermWriteOk in case of success

static inline external_term_write_result_t external_term_compute_external_size(term t, size_t *size, GlobalContext *glb)

Computes the size required for a external term.

This function should be called in order to calculate the required buffer size to store a serialized term in external term format.

Parameters:

• t – the term for which size is calculated

• size – the required buffer size

• glb – the global context

Returns:

ExternalTermWriteOk in case of success

static inline external_term_write_result_t external_term_serialize_term(term t, void *buf, GlobalContext *glb)

Serialize a term.

This function serializes in external term format given term, and writes it to the given buffer.

Parameters:

• t – the term that will be serialized

• buf – the buffer where the external term is written

• glb – the global context

Returns:

ExternalTermWriteOk in case of success