mojoler

# API

Modules load their `.so` from `priv/native` in `@on_load`. A missing file is a `load_nif` error from OTP, not a silent Elixir fallback that pretends the function ran.

## Mojoler.POC

`add/2` :: integer, integer -> integer. Values that do not fit in signed 64 bits, non-integers, and overflowing sums raise `ArgumentError`.

## Mojoler.Twice

`double/1` :: integer -> integer. Same badarg policy. Implemented with the generated ABI. The source does not declare the NIF structs.

## Mojoler.Term

Domain errors are `{:error, atom}`. Type errors are `ArgumentError`.

- `echo_i64/1`, `echo_u64/1`, `echo_i32/1`, `echo_u32/1`
- `add_i64/2` -> `{:ok, n}` | `{:error, :overflow}`
- `echo_f64/1` — no integer coercion
- `echo_atom/1` — `:ok`, `:error`, `:nil`, `true`, `false`, otherwise `{:error, :unknown_atom}`
- `copy_binary/1` -> `{:ok, binary, nbytes}` | `{:error, :not_binary | :too_large | :alloc}`. The size cap is 1_048_576 bytes.
- `borrow_stable/1` -> `{:ok, size, 1 | 0}` | `{:error, :not_binary}`
- `fill_output/1` -> `{:ok, binary}` filled with the byte 7, or `{:error, :bad_size}`
- `text_len/1` -> `{:ok, byte_size}` | `{:error, :invalid_utf8 | :not_binary}`
- `tuple_sum/1` — arity 2. Errors: `:not_tuple`, `:bad_arity`, `:bad_element`, `:overflow`
- `list_sum/1` — proper list, at most 64 integers. Errors: `:not_list`, `:improper_list`, `:too_long`, `:bad_element`, `:overflow`
- `map_n/1` — key `n`. Extra keys are dropped. Errors: `:missing`, `:bad_element`, `:map`

## Mojoler.Own

- `open_counter/0` returns a reference. `counter_add/2` -> `{:ok, n}` | `{:error, :closed}`. `counter_close/1` -> `:ok`, including a second close. A foreign handle raises `ArgumentError`. Collection sends `:counter_destroyed` once.
- `open_blob/1` -> reference | `{:error, :not_binary}`
- `blob_borrow/1` -> `{:ok, size}` | `{:error, :not_mutable}`
- `blob_release/1` and `blob_close/1` -> `:ok`
- `blob_freeze/1` -> `{:ok, binary}` | `{:error, :borrowed | :frozen}`
- `blob_token/1` -> `{:ok, integer}`
- `blob_poke/3` -> `:ok` | `{:error, :not_mutable | :bounds}`. A byte outside `0..255` raises `ArgumentError`.
- `blob_pin/1` returns a reference. `blob_dtors/0` returns how many blob destructors have run.
- `retain_binary/1` returns a reference. `read_retained/1` returns the copied term.

The resource binary from a successful freeze stays valid after `blob_close/1`.

## Mojoler.Sched

`burn/1` and `hold/2` run on a dirty CPU scheduler. `io_ping/0` runs on a dirty I/O scheduler. `Task.yield/2` does not cancel them.

## Mojoler.Dsl

Generated from `tools/dsl/decls.json`.

- `Mojoler.Dsl.Arith.add/2` -> `{:ok, n}` | `{:error, :overflow}`
- `Mojoler.Dsl.Bytes.shift/1` -> `{:ok, binary, nbytes}`
- `Mojoler.Dsl.Bytes.borrow_len/1` -> `{:ok, size}` | `{:error, :not_binary}`
- `Mojoler.Dsl.Box.open/0`, `bump/2`

## Mix tasks

- `mix compile` — includes `compile.mojoler`
- `mix mojoler.doctor`
- `mix mojoler.abi`
- `mix mojoler.inspect` — optional path, default `priv/native/libpoc.so`

## Not in this API

Raw pointers, a promise that `add/2` is faster than Elixir, GPU as a default dependency, and cancellation of a running NIF. Ownership rules are [ownership.md](ownership.md).