# `ExCodecs.NIF`
[🔗](https://github.com/AnimaLogica/codecs/blob/v0.2.4/lib/ex_codecs/nif.ex#L1)

Shared NIF result wrapping and the library-wide decompress size ceiling.

Compression codecs call `safe_call/2` around `ExCodecs.Native` functions so
callers always see `{:ok, binary()}` or `{:error, %ExCodecs.Error{}}`, never
raw `:erlang.nif_error/1` exceptions on the public API.

## Safety policy

Decompression defaults to a **256 MiB** output ceiling (`default_max_output_size/0`).
Override per call with `max_output_size:` (bytes). Exceeding the limit returns
`:output_limit_exceeded`.

## Panic classification

`safe_call/2` maps `:nif_not_loaded` precisely. Panic-like `ErlangError`
payloads are logged at warning and returned as `:compression_failed` with
message `"Native codec crashed"`.

# `default_max_output_size`

```elixir
@spec default_max_output_size() :: pos_integer()
```

Default decompress ceiling in bytes (256 MiB).

# `max_output_size`

```elixir
@spec max_output_size(keyword()) ::
  {:ok, pos_integer()} | {:error, ExCodecs.Error.t()}
```

Reads `:max_output_size` from `opts`, defaulting to `default_max_output_size/0`.

# `safe_call`

```elixir
@spec safe_call(atom(), (-> term())) :: {:ok, binary()} | {:error, ExCodecs.Error.t()}
```

Invokes a zero-arity NIF function and wraps ErlangError/`nif_not_loaded`.

# `wrap`

```elixir
@spec wrap(atom(), {:ok, binary()} | {:error, atom()} | term()) ::
  {:ok, binary()} | {:error, ExCodecs.Error.t()}
```

Wraps raw NIF `{:ok, binary}` / `{:error, atom}` results into `ExCodecs.Error`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*