# Receivers and Deferred Calls

> UForm for C

Every call stores its result in the `uform_outcome_t` it names: a status, and a static message that is `NULL` exactly on success.
`uform_completion_blocking_k`, the default, returns with the status final and every output readable.
`uform_completion_deferred_k` returns once the executor's own thread took the call, and the status reads `uform_status_deferred_k` until the call is final.
`uform_outcome_status` polls with acquire ordering and `uform_outcome_wait` blocks until final, and these are the only ways to read a status another thread may still store.
Submission copies the structure, while everything it points to stays borrowed until final.
An executor runs one call at a time: a call finding another one holding its executor finishes `uform_status_contended_k` without running, so a caller orders dependent calls by waiting on the first.
A call lets go of its arena, its handles and its executor before it stores the final status, so whoever reads it final may reuse all three at once.
A call stops early only when its `uform_progress_t` handler returns `uform_cancel_k`, and then finishes `uform_status_cancelled_k`.

```c
uform_outcome_t outcomes[4] = {0};
for (size_t shard = 0; shard != 4; ++shard) { // one executor per shard, each running one call at a time
    encodes[shard].outcome = &outcomes[shard];
    encodes[shard].executor = executors[shard];
    encodes[shard].completion = uform_completion_deferred_k;
    uform_image_encode(&encodes[shard]);
}
for (size_t shard = 0; shard != 4; ++shard) uform_outcome_wait(&outcomes[shard]);
```

### Inclusive and Exclusive Executors

The threads of an executor either include the thread that calls it or work without it.
A caller-inclusive pool needs its caller as one of its threads, so a deferred call on it runs at submission and is final when it returns.
A caller-exclusive pool has threads of its own: a deferred call returns as soon as the pool's thread 0 takes it, and that thread runs the call, forks included, and stores the status.
`uform_executor_for_ram` and `uform_executor_for_vram` spawn caller-exclusive pools wherever the build has threads, and WebAssembly's single thread is inclusive.
Because a deferred call needs nobody to drive it, one thread can keep several executors busy, here across UForm, USearch and UStore, by only reading status words:

```c
text_encode.completion = uform_completion_deferred_k;   // UForm, on a VRAM executor
dense_search.completion = usearch_completion_deferred_k; // USearch, on a RAM executor
blobs_read.completion = ustore_completion_deferred_k;    // UStore, on an NVMe executor
uform_text_encode(&text_encode);
usearch_dense_search(&dense_search);
ustore_blobs_read(&blobs_read);
while (uform_outcome_status(text_encode.outcome) == uform_status_deferred_k ||
       usearch_outcome_status(dense_search.outcome) == usearch_status_deferred_k ||
       ustore_outcome_status(blobs_read.outcome) == ustore_status_deferred_k)
    prepare_next_batch();
```

`#include <uform/types.h>`

## uform_outcome_t

Outcome of one call: a status every binding can branch on, and a static message carrying the detail the status cannot.

```c
struct uform_outcome_t
```

Messages are static and __don't__ need to be deallocated, and are `NULL` exactly when the status is [`uform_status_success_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_success_k).

- `status` `uform_status_t`: The status bindings branch on; [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k) until a deferred call settles.
- `message` `char const *`: The static detail, `NULL` exactly when `status` is [`uform_status_success_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_success_k).

## uform_continuation_t

Whether the call a handler is watching carries on or unwinds.

```c
enum uform_continuation_t
```

- `uform_continue_k` = `0`: Carry on to the next unit of work.
- `uform_cancel_k` = `1`: Stop and report [`uform_status_cancelled_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_cancelled_k).

## uform_progress_callback_t

Periodic report of a long call's advance, and the caller's chance to stop it.

```c
typedef uform_continuation_t(*) uform_progress_callback_t(size_t completed, size_t total, void *state);
```

Counts are in the units the verb consumes - items for an encoding, tensors for a load.

Never invoked concurrently, and never after the call it was passed to stores its final status.

Arguments, in order:

- `completed:` units finished so far, never decreasing across one call's reports.
- `total:` units the call will finish if it runs to completion.
- `state:` the opaque pointer registered alongside the handler, forwarded verbatim.

## uform_progress_t

How a long call reports its advance: a handler, its state, and how many reports it hears.

```c
struct uform_progress_t
```

A batch verb splits its items into `steps` nearly equal slices, hands each to its engine whole and reports after each; a load, whose engine counts its own tensors, forwards only the ticks that cross into the next slice. Without a handler the call runs as one slice and reports nothing.

- `callback` `uform_progress_callback_t`: The __optional__ handler; `NULL` skips every report.
- `state` `void *`: Opaque pointer forwarded into every `callback` call.
- `steps` `size_t`: Reports a call makes at most, the last at completion; zero derives to ten.

## uform_completion_t

Whether a call returns with its final status, or once submitted to its executor.

```c
enum uform_completion_t
```

- `uform_completion_blocking_k` = `0`: Return with the final status stored and every output readable; the default.
- `uform_completion_deferred_k` = `1`: Return once submitted, the status deferred until final; the caller waits or polls.

## uform_mood_t

What an executor does with its threads or streams once it goes idle.

```c
enum uform_mood_t
```

- `uform_mood_parked_k` = `0`: Sleep on futexes or events created with blocking sync, freeing the core.
- `uform_mood_spinning_k` = `1`: Poll them, trading a core for the lowest wake-up latency.

Spellings: ```
char const * uform_mood_name(uform_mood_t mood);
```

```
uform_mood_t uform_mood_from_name(uform_bytes_view_t name);
```

## uform_outcome_wait

Blocks on an atomic wait until `outcome` is final, with acquire ordering.

```c
uform_status_t uform_outcome_wait(uform_outcome_t *outcome);
```

Never wait on a call's own outcome from inside its progress handler: the call finishes only after it returns.

- `outcome` (in): An outcome passed to a call, read until its status leaves [`uform_status_deferred_k`](https://www.unum.cloud/docs/uform/c/errors.md#uform_status_deferred_k).

## uform_outcome_status

Reads the status of `outcome` without waiting, with the acquire ordering its final store pairs with, so a final status also publishes every output of the call.

```c
uform_status_t uform_outcome_status(uform_outcome_t *outcome);
```

The one way to poll: the status word is atomic only by this contract, so a caller reading the field directly needs an atomic load its language may not offer on foreign memory.

- `outcome` (in): An outcome passed to a call.