externalterm.h

Include dependency graph for externalterm.h:

digraph {
    graph [bgcolor="#00000000"]
    node [shape=rectangle style=filled fillcolor="#FFFFFF" font=Helvetica padding=2]
    edge [color="#1414CE"]
    "3" [label="stdbool.h" tooltip="stdbool.h"]
    "11" [label="assert.h" tooltip="assert.h"]
    "4" [label="stdint.h" tooltip="stdint.h"]
    "6" [label="stdlib.h" tooltip="stdlib.h"]
    "14" [label="utils.h" tooltip="utils.h"]
    "10" [label="term_typedef.h" tooltip="term_typedef.h"]
    "15" [label="stddef.h" tooltip="stddef.h"]
    "12" [label="limits.h" tooltip="limits.h"]
    "16" [label="refc_binary.h" tooltip="refc_binary.h"]
    "7" [label="string.h" tooltip="string.h"]
    "2" [label="term.h" tooltip="term.h"]
    "9" [label="erl_nif.h" tooltip="erl_nif.h"]
    "18" [label="resources.h" tooltip="resources.h"]
    "8" [label="memory.h" tooltip="memory.h"]
    "5" [label="stdio.h" tooltip="stdio.h"]
    "17" [label="list.h" tooltip="list.h"]
    "13" [label="inttypes.h" tooltip="inttypes.h"]
    "1" [label="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.h" tooltip="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.h" fillcolor="#BFBFBF"]
    "14" -> "15" [dir=forward tooltip="include"]
    "10" -> "11" [dir=forward tooltip="include"]
    "10" -> "12" [dir=forward tooltip="include"]
    "10" -> "13" [dir=forward tooltip="include"]
    "10" -> "4" [dir=forward tooltip="include"]
    "16" -> "3" [dir=forward tooltip="include"]
    "16" -> "6" [dir=forward tooltip="include"]
    "16" -> "17" [dir=forward tooltip="include"]
    "16" -> "18" [dir=forward tooltip="include"]
    "2" -> "3" [dir=forward tooltip="include"]
    "2" -> "4" [dir=forward tooltip="include"]
    "2" -> "5" [dir=forward tooltip="include"]
    "2" -> "6" [dir=forward tooltip="include"]
    "2" -> "7" [dir=forward tooltip="include"]
    "2" -> "8" [dir=forward tooltip="include"]
    "2" -> "16" [dir=forward tooltip="include"]
    "2" -> "14" [dir=forward tooltip="include"]
    "2" -> "10" [dir=forward tooltip="include"]
    "9" -> "10" [dir=forward tooltip="include"]
    "18" -> "6" [dir=forward tooltip="include"]
    "18" -> "9" [dir=forward tooltip="include"]
    "18" -> "17" [dir=forward tooltip="include"]
    "18" -> "8" [dir=forward tooltip="include"]
    "8" -> "9" [dir=forward tooltip="include"]
    "8" -> "10" [dir=forward tooltip="include"]
    "8" -> "14" [dir=forward tooltip="include"]
    "8" -> "4" [dir=forward tooltip="include"]
    "8" -> "6" [dir=forward tooltip="include"]
    "1" -> "2" [dir=forward tooltip="include"]
}

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

digraph {
    graph [bgcolor="#00000000"]
    node [shape=rectangle style=filled fillcolor="#FFFFFF" font=Helvetica padding=2]
    edge [color="#1414CE"]
    "3" [label="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/module.c" tooltip="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/module.c"]
    "4" [label="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/nifs.c" tooltip="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/nifs.c"]
    "2" [label="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.c" tooltip="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.c"]
    "1" [label="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.h" tooltip="/home/runner/work/AtomVM/AtomVM/src/libAtomVM/externalterm.h" fillcolor="#BFBFBF"]
    "1" -> "2" [dir=back tooltip="include"]
    "1" -> "3" [dir=back tooltip="include"]
    "1" -> "4" [dir=back tooltip="include"]
}

External term deserialization functions.

This header provides external term deserialization functions.

Enums

enum ExternalTermResult

Values:

enumerator EXTERNAL_TERM_OK = 0
enumerator EXTERNAL_TERM_BAD_ARG = 1
enumerator EXTERNAL_TERM_MALLOC = 2
enumerator EXTERNAL_TERM_HEAP_ALLOC = 3
enum ExternalTermOpts

Values:

enumerator ExternalTermNoOpts = 0
enumerator ExternalTermToHeapFragment = 1

Functions

term externalterm_to_term(const void *external_term, size_t size, Context *ctx, ExternalTermOpts opts)

Gets a term from external term data.

Deserialize an external term from external format and returns a term.

Parameters:
  • external_term – the external term that will be deserialized.

  • size – to allocate for term.

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

  • opts – if non-zero, use a heap fragment to store the generated terms. Otherwise, use the heap in the provided context. Note that when using the context heap, this function may call the GC, if there is insufficient space to store the generated terms.

Returns:

a term.

enum ExternalTermResult externalterm_from_binary(Context *ctx, term *dst, term binary, size_t *bytes_read)

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 externalterm_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.

  • dst – a pointer to a term that will contain the binary encoded term.

  • binary – the binary.

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

Returns:

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

term externalterm_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. This function is the complement of externalterm_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.

  • t – the term to return as binary.

Returns:

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