Skip to content

Elixir guide

How to use Elixir modules generated by DeukPack in your backend ecosystem. Perfect for massively concurrent game servers, chat systems, and real-time OTP node architectures.

1. Code generation

Specify --elixir to generate Erlang BEAM compatible Elixir modules from your IDL.

npx deukpack ./schema.deuk ./gen --elixir --protocol tbinary

Output is generated as DeukPack.*.ex modules corresponding to your IDL namespaces and structs. The compiler leverages Elixir's macro and binary pattern matching systems to guarantee native BEAM-level execution speed.

2. Including in the project (Mix)

  • Simply move the generated *.ex files into your Mix project's /lib directory or any compiled path configured in mix.exs.
  • Elixir will automatically compile them alongside your project code without requiring any external C++ NIFs or dependencies.

3. Serialization & deserialization — 2-Method Standard (v1.7.6+)

Generated Elixir types use Erlang's hardware-accelerated binary pattern matching (<<tag::integer, rest::binary>>) for native BEAM-level speed.

Function Signature Purpose
pack/1 pack(struct) Serialize to binary (default)
pack/2 pack(struct, :json) Serialize to JSON string
unpack/1 unpack(bytes) Create new struct from binary
unpack/2 unpack(bytes, :json) Create new struct from JSON
unpack/2 unpack(struct, bytes) Merge bytes into existing struct 
# Define your struct
user = %DeukPack.DemoUser{
  id: 1,
  name: "Alice",
  home: %DeukPack.Vector2{x: 10.0, y: 20.0}
}

# Pack to binary (default)
bin = DeukPack.DemoUser.pack(user)

# Pack to JSON
json = DeukPack.DemoUser.pack(user, :json)

# Unpack → new struct from binary
decoded = DeukPack.DemoUser.unpack(bin)
IO.inspect(decoded.name)  # "Alice"

# Unpack → new struct from JSON
from_json = DeukPack.DemoUser.unpack(json, :json)

# Unpack into existing struct (merge / zero-alloc pattern)
cached = DeukPack.DemoUser.unpack(cached, bin)

4. Native OTP Integration

DeukPack structures translate directly to Elixir defstruct, making them naturally compatible with native GenServer state maps, ETS tables, and Ecto changeset layers. Because DeukPack enforces the Zero-Overhead policy and implements MAX_SAFE_LENGTH checks before payload extraction, you can safely pipe raw TCP sockets (like ranch or :gen_tcp) directly through the decoder without exposing your BEAM limits to network memory bombs.

5. Next steps