ToonEx.Btoon.Schema (toon_ex v1.3.1)

Copy Markdown View Source

A named, typed record schema for schema-mode encoding.

In schema mode the encoder omits keys and type tags entirely, emitting SchemaID followed by ordered, fixed-width values. The decoder reads the values strictly according to the schema, which is either embedded in the envelope (schema flag) or supplied through Btoon.decode/2 options.

Field types are Btoon.ElementType atoms: fixed-width numeric types (:int8..:float64), plus :null, :bool, :string, :binary, :array and :object.

Persistent Term Storage

For sharing a schema across many processes without deep-copying on each message send, use :persistent_term:

iex> schema = Btoon.Schema.new(100, "Player", [%{name: "id", type: :int32}])
iex> Btoon.Schema.put_persistent(:player_schema, schema)
iex> schema = Btoon.Schema.get_persistent(:player_schema)
iex> Btoon.Schema.fields(schema)
[%{name: "id", type: :int32}]

Examples

iex> schema = Btoon.Schema.new(100, "Player", [
...>   %{name: "id", type: :int32},
...>   %{name: "x", type: :float32},
...>   %{name: "y", type: :float32},
...>   %{name: "hp", type: :uint16}
...> ])
iex> Btoon.Schema.fields(schema)
[%{name: "id", type: :int32}, %{name: "x", type: :float32}, %{name: "y", type: :float32}, %{name: "hp", type: :uint16}]

Summary

Types

field()
t()

Functions

delete_persistent(key)

Deletes a schema from :persistent_term.

field_count(schema)

Number of fields.

fields(schema)

Returns the field definitions.

get_persistent(key)

Retrieves a schema from :persistent_term.

id(schema)

Returns the schema id.

name(schema)

Returns the schema name.

new(id, name, fields)

Builds a schema from an id, name and field list.

put_persistent(key, schema)

Stores a schema in :persistent_term under the given key.

Types

field()

@type field() :: %{name: String.t(), type: ToonEx.Btoon.Types.element_type()}

t()

@type t() :: %ToonEx.Btoon.Schema{
  envelope: iodata(),
  envelope_size: non_neg_integer(),
  fields: [field()],
  id: integer(),
  name: String.t()
}

Functions

delete_persistent(key)

@spec delete_persistent(term()) :: :ok

Deletes a schema from :persistent_term.

Warning: this triggers a full garbage collection sweep across all processes on the node. Use sparingly.

field_count(schema)

@spec field_count(t()) :: non_neg_integer()

Number of fields.

fields(schema)

@spec fields(t()) :: [field()]

Returns the field definitions.

get_persistent(key)

@spec get_persistent(term()) :: {:ok, t()} | :error

Retrieves a schema from :persistent_term.

Returns {:ok, schema} or :error if the key doesn't exist.

id(schema)

@spec id(t()) :: integer()

Returns the schema id.

name(schema)

@spec name(t()) :: String.t()

Returns the schema name.

new(id, name, fields)

@spec new(integer(), String.t(), [field()]) :: t()

Builds a schema from an id, name and field list.

put_persistent(key, schema)

@spec put_persistent(term(), t()) :: :ok

Stores a schema in :persistent_term under the given key.

Data in :persistent_term lives outside process heaps and is shared across all processes on the node without copying on read. Updates are expensive (global GC), so use only for write-once data like schemas defined at application startup.

Example

iex> schema = Btoon.Schema.new(100, "Player", [%{name: "id", type: :int32}])
iex> Btoon.Schema.put_persistent(:player_schema, schema)
:ok