# Receivers and Deferred Calls

> UForm for Python

A receiver carries what every C argument structure puts before its inputs: the executor and the completion.
The model runs a verb on the calling thread, `model.on(executor)` answers a `uform.On` whose verbs block on that executor, and `model.deferred(executor)` answers a `uform.DeferredOn` whose verbs submit there and answer a `uform.Deferred`.
The receiver's type alone chooses the completion, so all three offer the same verbs with the same arguments.
In a coroutine, `await` a deferred call; anywhere else, `wait()` blocks the thread with its state detached:

```python
call = model.deferred(executor).image_encode(files, uform.Arena(executor))
encoded = await call  # or: call.wait()
```

`call.status` polls without waiting, reading `Status.DEFERRED` until the call is final.
Dropping a `Deferred` waits for its call first, since the library still reads the inputs it holds.
A trainer runs `step` and `save` blocking on the executor it was created on, and `trainer.on(...)` and `trainer.deferred(...)` choose another completion.

`import uform`

`from uform import Deferred, On, DeferredOn`

## Mood

What an executor does once it goes idle, valued as `uform_mood_t`: sleep, or keep polling.

```python
class Mood(IntEnum)
```

- `PARKED` = `0`
- `SPINNING` = `1`

## Deferred

A call a [`DeferredOn`](#DeferredOn) submitted: `await` it, or `wait()` for it; dropping it waits.

```python
class Deferred[AnswerT]
```

## __class_getitem__

Names what `wait()` answers, as `Deferred[Encoded]`.

```python
def __class_getitem__(item: Any, /) -> GenericAlias
```

## wait

Blocks until the call is final, then answers or raises.

```python
def wait() -> AnswerT
```

Calls `uform_outcome_wait`.

## __await__

Runs `wait()` on the running event loop's default executor, suspending the task meanwhile.

```python
def __await__() -> Generator[Any, None, AnswerT]
```

## status

[`Status.DEFERRED`](https://www.unum.cloud/docs/uform/python/errors.md#DEFERRED) until the call is final, then the final one.

```python
status: Status
```

Calls `uform_outcome_status`.

## On

A model or trainer bound to the executor its verbs block on, as `model.on(executor)` answers it.

```python
class On[TargetT]
```

## __class_getitem__

Names the target the receiver addresses, as `On[Model]`.

```python
def __class_getitem__(item: Any, /) -> GenericAlias
```

## *

```python
def describe() -> ModelDescription
```

- `describe`
- `step`
- `save`
- `describe`
- `step`
- `save`

## *_encode

```python
def text_encode(
    texts: _Texts,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: TextEncodeStats | None = None,
) -> Encoded
```

- `text_encode`
- `image_encode`
- `video_encode`
- `audio_encode`
- `text_encode`
- `image_encode`
- `video_encode`
- `audio_encode`

## image_encode_*_encode_pixels

```python
def image_encode__encode_pixels(
    pixels: Sequence[Buffer],
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: ImageEncodeStats | None = None,
) -> Encoded
```

## audio_encode_*_encode_samples

```python
def audio_encode__encode_samples(
    samples: Sequence[Buffer] | _Tape,
    sample_rate: int,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: AudioEncodeStats | None = None,
) -> Encoded
```

## text_*_choose

```python
def text__choose(
    texts: _Texts,
    choices: _Texts,
    arena: Arena,
    /,
    *,
    temperature_groups: _Words | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: TextEncodeStats | None = None,
) -> RowsTape
```

## DeferredOn

A model or trainer bound to the executor its verbs submit to, each answering a [`Deferred`](#Deferred) at once.

```python
class DeferredOn[TargetT]
```

## __class_getitem__

Names the target the receiver addresses, as `DeferredOn[Model]`.

```python
def __class_getitem__(item: Any, /) -> GenericAlias
```