# `Pristine.Cancellation`
[🔗](https://github.com/nshkrdotcom/pristine/blob/pristine-v0.4.0/lib/pristine/cancellation.ex#L1)

Opaque, process-safe cancellation token for a logical unary request.

A token starts active and becomes permanently cancelled after `cancel/1`.
Cancellation is idempotent and may be triggered from any BEAM process.

The token is a one-shot lifecycle signal. It may be intentionally shared by
multiple related requests, but once cancelled it can never be reset or reused
as an active token. Cancelling it does not roll back a remote side effect and
does not prove that an upstream service never received or started processing a
request.

# `await_result`

```elixir
@type await_result() :: :cancelled | :timeout
```

# `t`

```elixir
@opaque t()
```

# `await`

```elixir
@spec await(t(), timeout()) :: await_result()
```

Wait for cancellation for up to `timeout` milliseconds.

Returns `:cancelled` as soon as cancellation is observed or `:timeout` when
the supplied timeout expires. Waiting does not consume the token; cancellation
remains terminal and observable by later callers.

# `cancel`

```elixir
@spec cancel(t()) :: :ok
```

Permanently cancel a token.

The first caller transitions the token and wakes current waiters. Repeated or
concurrent calls are harmless and return `:ok`.

# `cancelled?`

```elixir
@spec cancelled?(t()) :: boolean()
```

Return whether the token has been cancelled.

# `new`

```elixir
@spec new() :: t()
```

Create a new active cancellation token.

---

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