Daemon: batched forks
cua.daemon.v1 batched forks: many sandboxes from checkpoints at once, on this machine or across your machines.
Requests and events of SandboxService.ForkSandboxBatch: groups of forks of one checkpoint placed together on one machine, checkpoints spread over the least-loaded machines, each fork streamed as it is ready.
Source: libs/cua/proto/cua/daemon/v1/fork_batch.proto.
ForkBatchService#
cua.daemon.v1.ForkBatchService
Batched forks, served by the local cua daemon next to SandboxService.
| RPC | Request | Response | Kind |
|---|---|---|---|
ForkSandboxBatch | ForkSandboxBatchRequest | ForkSandboxBatchResponse | server stream |
ForkBatchService.ForkSandboxBatch#
/cua.daemon.v1.ForkBatchService/ForkSandboxBatch, server stream: ForkSandboxBatchRequest to ForkSandboxBatchResponse.
Forks many sandboxes from checkpoints at once, on this machine or
across your machines. Streams each fork as soon as it is ready (or
failed), then one done. A fork that fails does not stop the others,
and the batch runs to completion if the caller goes away.
Types in cua/daemon/v1/fork_batch.proto#
ForkBatchGroup#
The forks of one checkpoint that go to one machine together.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | The checkpoint (or local sandbox) to fork. |
count | 2 | uint32 | How many forks. |
name_prefix | 3 | string | Names are <name_prefix>-<n>. Empty: the batch's prefix, else <source>-<random>. |
ForkSandboxBatchRequest#
Request for SandboxService.ForkSandboxBatch.
| Field | # | Type | Description |
|---|---|---|---|
source | 1 | string | Shorthand for one checkpoint: fork source count times, in groups of group_size. Leave empty when groups is set. |
count | 2 | uint32 | How many forks of source. |
group_size | 3 | uint32 | Forks of source per group (0: all in one group). |
groups | 4 | repeated ForkBatchGroup | The groups, each of one checkpoint, when the batch has several checkpoints. |
on | 5 | string | Where: empty or local (this machine), auto (your machines that provide Spaces, this one included, least loaded first), or host:<machine> (one machine). |
max_parallel_per_host | 6 | uint32 | Forks started at once on one machine (0: 4). |
cpus | 8 | uint32 | vCPUs each fork is counted as when placing (0: 1; forks of one world are mostly idle and share its pages). |
memory_mb | 9 | uint64 | Memory (MiB) each fork is counted as when placing (0: the checkpoint's when this machine holds it, else 2048). |
name_prefix | 10 | string | Name prefix for groups without their own. |
fallback | 11 | SnapshotFallback | Where machines fetch a checkpoint they do not hold when the machine that has it cannot be reached. |
retries | 12 | uint32 | How many times forks that failed because their machine failed are placed again on another machine (0: once; set no_retry for never). |
no_retry | 13 | bool | Never place failed forks again. |
ForkBatchPlacement#
Where a group goes.
| Field | # | Type | Description |
|---|---|---|---|
group | 1 | uint32 | The group (index into the batch's groups). |
source | 2 | string | Its checkpoint. |
host | 3 | string | The machine (local for this one). |
count | 4 | uint32 | How many of its forks go there (a group too big for one machine is split, and placed in several parts). |
attempt | 5 | uint32 | 1 for the first placement; higher when forks are placed again after their machine failed. |
needs_sync | 6 | bool | The machine does not hold the checkpoint yet: it is copied there first. |
reason | 7 | string | Why it went there, for people. |
ForkBatchSummary#
The end of a batch.
| Field | # | Type | Description |
|---|---|---|---|
ok | 1 | uint32 | Forks that are ready. |
failed | 2 | uint32 | Forks that failed. |
elapsed_ms | 3 | uint64 | Milliseconds the batch took. |
per_host | 4 | map of string to uint32 | Ready forks per machine. |
peak_parallel | 5 | map of string to uint32 | Most forks that were starting at once on one machine. |
ForkBatchItem#
One fork of a batch.
| Field | # | Type | Description |
|---|---|---|---|
index | 1 | uint32 | Its index in the batch (groups in order, forks in order). |
group | 2 | uint32 | Its group. |
source | 3 | string | Its checkpoint. |
name | 4 | string | Its name. |
host | 5 | string | The machine it runs on (local for this one). |
space | 6 | string | The Space it is, to connect to: local:<name>, direct:<addr> or relay:<machine>. Empty when it failed. |
error | 8 | string | Why it failed. Empty when it is ready. |
error_code | 9 | string | A short machine-readable reason with error: host_failed, no_capacity, sync_failed, fork_failed, no_host. |
attempt | 10 | uint32 | Which placement it came from (1: the first). |
elapsed_ms | 11 | uint64 | Milliseconds from the start of the batch until it was ready (or failed). |
fork_ms | 12 | uint64 | Milliseconds its own fork took, on its machine. |
ForkSandboxBatchResponse#
One event of ForkBatchService.ForkSandboxBatch.
| Field | # | Type | Description |
|---|---|---|---|
placement | 1 | ForkBatchPlacement (oneof event) | A group was placed on a machine. |
sync | 2 | SnapshotSyncProgress (oneof event) | A checkpoint is being copied to a machine. |
item | 3 | ForkBatchItem (oneof event) | One fork is ready, or failed. |
done | 4 | ForkBatchSummary (oneof event) | The batch is over (the last event). |
sandbox | 5 | Sandbox | With a ready item on this machine: its sandbox. |