# Receivers and Deferred Calls

> UForm for Swift

The receiver chooses where a verb runs and how it completes, and the verb stays the same.
Called on the model, a verb runs on the calling thread; on `model.on(executor)` it blocks on that executor, throwing `contended` while another call holds it; on `model.deferred(executor)` it submits there and answers a `Deferred` at once.

```swift
let here = try model.textEncode(texts, arena: arena)                  // the calling thread
let blocking = try model.on(executor).textEncode(texts, arena: arena) // blocking, on the executor
let call = try model.deferred(executor).imageEncode(files, arena: arena) // Deferred<Encoded>
let images = try await call.value  // or: try call.wait()
```

A `Deferred` owns its outcome, its outputs and copies of its inputs until the call is final, so the caller's arrays may go at once.
It borrows the model, the executor and the arena as a blocking call does, since releasing any of them waits for the calls naming it.
`status` reads `deferred` until then, through `uform_outcome_status`, and `wait()` blocks through `uform_outcome_wait` and answers the result or throws the failure, the same every time it is asked.
`value` waits on a Dispatch thread and then reads the result in the caller's isolation, so an `async` caller suspends rather than blocks.
Releasing an unfinished one waits for it first.

```swift
let call = try model.deferred(executor).audioEncode(recordings, arena: arena)
if call.status == .deferred {
    // other work
}
let encoded = try await call.value  // or: try call.wait()
```

A failure this binding catches before the call crosses, like heights and widths that do not name one per image, throws at submission, and one the library catches arrives through `status` and `wait`.
A call finding another one holding its executor finishes at once with `contended`.

`import UForm`

## Progress

A periodic report of a long call's advance - units finished and units in total, items for an encoding and tensors for a load - and the caller's chance to stop it.

```swift
typealias Progress = @Sendable (_ completed: Int, _ total: Int) -> Continuation
```

Never invoked concurrently, so it needs no synchronization of its own, but it runs on whichever
thread advanced the work, hence `@Sendable`.

## Mood

What an executor does with its threads or streams once it goes idle, carrying the C enumerator.

```swift
struct Mood
```

Conforms to: `Hashable`, `Sendable`, `CustomStringConvertible`, `Equatable`

## parked

Idle threads and streams sleep, freeing the core.

```swift
static let parked: Mood
```

## spinning

Idle threads and streams poll, trading a core for the lowest wake-up latency.

```swift
static let spinning: Mood
```

## description

The mood as the library spells it.

```swift
var description: String { get }
```

Calls `uform_mood_name`.

## init

Reads a spelling back, and nil for one no mood carries.

```swift
init?(name: String)
```

Calls `uform_mood_from_name`.

## Continuation

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

```swift
enum Continuation
```

- `continue`: Carry on to the next unit of work.
- `cancel`: Stop, and report [`cancelled`](https://www.unum.cloud/docs/uform/swift/errors.md#cancelled).

Conforms to: `Equatable`, `Hashable`, `Sendable`

## Deferred

A call submitted to an executor, which finishes there while the caller does other work.

```swift
final class Deferred<Value>
```

It owns the call's outcome, outputs and copied inputs until the call is final. The handles it
names, the arena among them, it borrows as a blocking call does. Releasing an unfinished one
waits for it first.

Conforms to: `Sendable`

## status

[`deferred`](https://www.unum.cloud/docs/uform/swift/errors.md#deferred) until the call is final, then [`success`](https://www.unum.cloud/docs/uform/swift/errors.md#success) or its failure, read without blocking.

```swift
var status: Status { get }
```

Calls `uform_outcome_status`.

## wait

Blocks until the call is final, then answers its result or throws its failure, the same every time it is asked.

```swift
func wait() throws(UFormError) -> Value
```

Calls `uform_outcome_wait`.

## value

Waits for the call on a Dispatch thread, so an `async` caller suspends rather than blocks and the cooperative pool keeps every thread; the result is read back in the caller's isolation.

```swift
nonisolated(nonsending) var value: Value { get async throws(UFormError) }
```

Binding-only: runs [`wait`](#wait).

## ModelOn

A model's verbs on an executor, each blocking until final after every call submitted there before it; see `Model.on(_:)` and the model's own verbs for what each one does.

```swift
struct ModelOn
```

Conforms to: `Sendable`

## text*

Calls `uform_text_encode`.

```swift
func textEncode(
    _ texts: [String],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## image*

Calls `uform_image_encode`.

```swift
func imageEncode(
    _ images: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## imageEncode*

Calls `uform_image_encode_pixels`.

```swift
func imageEncodePixels(
    _ pixels: [[UInt8]],
    heights: [UInt32],
    widths: [UInt32],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## video*

Calls `uform_video_encode`.

```swift
func videoEncode(
    _ videos: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## audio*

Calls `uform_audio_encode`.

```swift
func audioEncode(
    _ recordings: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## audioEncode*

Calls `uform_audio_encode_samples`.

```swift
func audioEncodeSamples(
    _ samples: [[Float]],
    sampleRate: UInt32,
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

## text*

Calls `uform_text_choose`.

```swift
func textChoose(
    _ texts: [String],
    choices: [[UInt8]],
    temperatureGroups: [UInt32]? = nil,
    arena: Arena,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Chosen
```

## *

Calls `uform_model_describe`.

```swift
func describe() throws(UFormError) -> ModelDescription
```

## ModelDeferredOn

A model's verbs submitted to an executor, each answered at once as a [`Deferred`](#Deferred) that finishes there.

```swift
struct ModelDeferredOn
```

A deferred call copies its inputs, so the caller's arrays may go at once. The model, the
executor and the arena are borrowed as a blocking call borrows them, since releasing any of them
waits for the calls naming it.

Conforms to: `Sendable`