# Dista API reference

> The `dista` package, from Dista 0.2.1, as published on mojoshelf (commit 9e4839937d82), by `mojo doc` from Mojo 1.2.0.

## Modules

- [dista.checkpoint](https://magmalake.dev/s/dista/api/checkpoint.md): Where actor checkpoints live: objects under `DISTA_CHECKPOINT_URI`.
- [dista.client](https://magmalake.dev/s/dista/api/client.md): The driver's side of the protocol: submitting tasks, calling actors and getting results back from the head.
- [dista.codec](https://magmalake.dev/s/dista/api/codec.md): Turning task arguments and results into bytes and back.
- [dista.conn](https://magmalake.dev/s/dista/api/conn.md): A non-blocking framed connection, for the head's event loop.
- [dista.frame](https://magmalake.dev/s/dista/api/frame.md): Length-prefixed messages between drivers, the head and workers.
- [dista.head](https://magmalake.dev/s/dista/api/head.md): The head: one event loop that schedules every driver's tasks onto workers.
- [dista.metrics](https://magmalake.dev/s/dista/api/metrics.md): Prometheus metrics: counters and a histogram, and the `/metrics` page.
- [dista.runtime](https://magmalake.dev/s/dista/api/runtime.md): The runtime: one binary that runs as driver, head or worker.
- [dista.scale](https://magmalake.dev/s/dista/api/scale.md): How many workers a running job wants: a policy over the head's demand.
- [dista.seq](https://magmalake.dev/s/dista/api/seq.md): `Seq[T]`: a list that goes through the codec.
- [dista.signals](https://magmalake.dev/s/dista/api/signals.md): SIGTERM: the head exits, and a worker drains, even as a container's PID 1.
- [dista.socket](https://magmalake.dev/s/dista/api/socket.md): IPv4 TCP and process control over libc.
- [dista.store](https://magmalake.dev/s/dista/api/store.md): The node-local object store: large results in shared mappings.
- [dista.task](https://magmalake.dev/s/dista/api/task.md): Tasks: remote functions, their IDs, and how a worker runs one.
- [dista.worker](https://magmalake.dev/s/dista/api/worker.md): A worker: runs tasks for the head and serves its results to peers.

dista: distributed tasks for Mojo.

Declare a remote function as a task, start a runtime with it registered, and
call it:

```mojo
from dista import Runtime, Task

def square(x: Int) -> Int:
    return x * x

comptime Square = Task[Int, Int, square]

def main() raises:
    var rt = Runtime[Square](workers=4)
    var r = rt.remote[Square](7)
    print(rt.get(r))  # 49
```

An actor keeps state between calls on a worker of its own:

```mojo
comptime CounterActor = Actor[Counter, Int, new_counter]
comptime Add = Method[CounterActor, Int, Int, add]

var rt = Runtime[CounterActor, Add](workers=2)
var c = rt.create[CounterActor](0)
var total = rt.call[Add](c, 5)  # an ObjectRef[Int]
rt.kill(c)
```

See DESIGN.md for how it works.