Batched forks

Fork checkpoints many times at once, on this machine or across your machines, each fork streamed as it is ready.

fork_many and fork_groups start many sandboxes from checkpoints at once and return a ForkBatch whose events arrive as they happen: where each group went, the copy of a checkpoint to a machine that lacked it, each fork ready (or failed, alone), and last the summary. With on = "auto" a group's forks go to one of your machines, so they share the checkpoint's memory there; groups of different checkpoints spread over the least-loaded machines; a checkpoint is copied (and its files verified by SHA-256) to a machine that lacks it, straight from the machine that holds it, else from the fallback that publish_checkpoint fills; forks of a machine that fails are placed again. The CLI is cua sb fork-many and cua sb publish.

Batch methods#

Methods of Sandboxes.

`Sandboxes.fork_many`#

Forks checkpoint source count times at once and returns the running batch: each fork is reported as soon as it is ready (or failed: one failure does not stop the others). source may also be a local sandbox, running or stopped: it is checkpointed once (memory saved once, shared copy-on-write by the forks on QEMU) and that checkpoint is deleted with the last of its forks. With on = "auto" the forks go to your machines that provide Spaces: each group (group_size forks) to one machine, groups spread over the least loaded ones, the checkpoint copied (and verified) to a machine that lacks it first; a machine that fails has its forks placed again on another.

async def fork_many(self, source: str, count: int, options: Optional[ForkManyOptions]) -> ForkBatch

Parameter	Type	Default
`source`	`String`	required
`count`	`u32`	required
`options`	`Option<ForkManyOptions>`	required

Returns ForkBatch · Async · Raises CuaError

`Sandboxes.fork_groups`#

Sandboxes.fork_many for several checkpoints at once: each group (the forks of one checkpoint that belong together) goes to one machine, and groups of different checkpoints spread.

async def fork_groups(self, groups: List[ForkGroup], options: Optional[ForkManyOptions]) -> ForkBatch

Parameter	Type	Default
`groups`	`Vec<ForkGroup>`	required
`options`	`Option<ForkManyOptions>`	required

Returns ForkBatch · Async · Raises CuaError

`Sandboxes.publish_checkpoint`#

Uploads checkpoint name to fallback (S3, or a folder every machine mounts), so batches on your other machines copy it from there when this machine cannot be reached. Files already there are not uploaded again. Returns the bytes uploaded.

async def publish_checkpoint(self, name: str, fallback: SnapshotFallbackOptions) -> int

Parameter	Type	Default
`name`	`String`	required
`fallback`	`SnapshotFallbackOptions`	required

Returns u64 · Async · Raises CuaError

`ForkBatch`#

A running batch of forks. Its events as they happen (ForkBatch.next), or all of it (ForkBatch.collect).

Returned by Sandboxes.fork_groups, Sandboxes.fork_many.

Method	Description
`collect`	Waits for the whole batch: every fork (ready or failed), by index, and the summary.
`next`	The next event: a placement, a copy's progress, a fork that is ready (or failed), and last the summary.

`ForkBatch.collect`#

Waits for the whole batch: every fork (ready or failed), by index, and the summary. After some or all of the events were read with ForkBatch.next, it still returns the whole batch: the forks already read plus the rest, with the summary.

async def collect(self) -> ForkBatchResult

Returns ForkBatchResult · Async · Raises CuaError

`ForkBatch.next`#

The next event: a placement, a copy's progress, a fork that is ready (or failed), and last the summary. None after the summary.

async def next(self) -> Optional[ForkBatchEvent]

Returns Option<ForkBatchEvent> · Async · Raises CuaError

`ForkManyOptions` record#

Batched fork options. For Sandboxes.fork_many and Sandboxes.fork_groups.

Field	Type	Default	Description
`on`	`Option<String>`	`None`	Where: `local` (this machine, the default), `auto` (your machines that provide Spaces, this one included, least loaded first) or `host:<machine>`.
`group_size` / `groupSize`	`u32`	`0`	Forks per group for `Sandboxes.fork_many` (0: all in one group). A group's forks go to one machine, so they share the checkpoint's memory there.
`max_parallel_per_host` / `maxParallelPerHost`	`u32`	`0`	Forks started at once on one machine (0: 4).
`name_prefix` / `namePrefix`	`String`	`""`	Names are `<prefix>-<n>` (empty: `<checkpoint>-<random>`).
`cpus`	`u32`	`0`	vCPUs each fork is counted as when placing (0: 1, as forks of one world are mostly idle).
`memory_mb` / `memoryMb`	`u64`	`0`	Memory (MiB) each fork is counted as when placing (0: the checkpoint's).
`retries`	`u32`	`0`	Times forks of a machine that failed (or was full) are placed again on another (0: once).
`no_retry` / `noRetry`	`bool`	`false`	Never place failed forks again: report them.
`fallback`	`Option<SnapshotFallbackOptions>`	`None`	Where machines fetch a checkpoint they lack when the one that holds it cannot be reached.

`ForkGroup` record#

A group of forks. The forks of one checkpoint that go to one machine together (Sandboxes.fork_groups).

Field	Type	Default	Description
`source`	`String`		The checkpoint, or a local sandbox (see `Sandboxes.fork_many`).
`count`	`u32`		How many forks.
`name_prefix` / `namePrefix`	`String`	`""`	Names are `<prefix>-<n>` (empty: the batch's).

`SnapshotFallbackOptions` record#

A fallback copy of checkpoints. Your machines fetch a checkpoint there when the machine that holds it cannot be reached (Sandboxes.publish_checkpoint puts it there). Set s3_bucket (S3, with each machine's AWS credentials) or dir (a folder every machine mounts, such as your Cua Volume).

Field	Type	Default	Description
`s3_bucket` / `s3Bucket`	`String`	`""`	S3 bucket.
`s3_prefix` / `s3Prefix`	`String`	`""`	Key prefix in the bucket (`cua-snapshots/`).
`s3_region` / `s3Region`	`String`	`""`	Region (empty: each machine's AWS default).
`s3_endpoint` / `s3Endpoint`	`String`	`""`	An S3-compatible endpoint (empty: AWS).
`dir`	`String`	`""`	A folder every machine mounts (`~` is each machine's home), for example `~/Cua Volume/snapshots`.

`ForkBatchEvent` enum#

A batch event.

ForkBatchEvent.PLACEMENT(placement: ForkBatchPlacement)
ForkBatchEvent.SYNC(progress: SnapshotSyncProgress)
ForkBatchEvent.ITEM(item: ForkBatchItem)
ForkBatchEvent.DONE(summary: ForkBatchSummary)

Variant	Description
`Placement`	A group was placed. Fields: `placement: ForkBatchPlacement`
`Sync`	A checkpoint is being copied to a machine. Fields: `progress: SnapshotSyncProgress`
`Item`	A fork is ready, or failed. Fields: `item: ForkBatchItem`
`Done`	The batch is over (the last event). Fields: `summary: ForkBatchSummary`

`ForkBatchItem` record#

One fork of a batch. Ready, or failed with why.

Field	Type	Description
`index`	`u32`	Its index in the batch.
`group`	`u32`	Its group.
`source`	`String`	Its checkpoint.
`name`	`String`	Its name.
`host`	`String`	The machine it runs on (`local` for this one).
`space`	`String`	The Space to connect to (`local:<name>`, `direct:<addr>`, `relay:<machine>`); empty when it failed.
`error`	`String`	Why it failed; empty when it is ready.
`error_code` / `errorCode`	`String`	`host_failed`, `no_capacity`, `sync_failed`, `fork_failed` or `no_host` with `error`.
`attempt`	`u32`	Which placement it came from (1: the first).
`elapsed_ms` / `elapsedMs`	`u64`	Milliseconds from the start of the batch until it was ready.
`fork_ms` / `forkMs`	`u64`	Milliseconds its own fork took.

`ForkBatchPlacement` record#

A group's placement. Where its forks went.

Field	Type	Description
`group`	`u32`	The group.
`source`	`String`	Its checkpoint.
`host`	`String`	The machine.
`count`	`u32`	How many of its forks go there.
`attempt`	`u32`	1 for the first placement, higher when placed again.
`needs_sync` / `needsSync`	`bool`	The checkpoint is copied there first.
`reason`	`String`	Why there.

`SnapshotSyncProgress` record#

A checkpoint copy's progress. Copying it to a machine that lacked it.

Field	Type	Description
`name`	`String`	The checkpoint.
`digest`	`String`	Its digest.
`from`	`String`	Where the bytes come from now (a machine, `s3`, `volume`).
`bytes_done` / `bytesDone`	`u64`	Bytes copied.
`bytes_total` / `bytesTotal`	`u64`	Bytes to copy in all.
`bytes_reused` / `bytesReused`	`u64`	Bytes the machine had already.
`done`	`bool`	Finished.
`verified`	`bool`	Every file matched its SHA-256.

`ForkBatchSummary` record#

A batch's summary.

Field	Type	Description
`ok`	`u32`	Forks that are ready.
`failed`	`u32`	Forks that failed.
`elapsed_ms` / `elapsedMs`	`u64`	Milliseconds the batch took.
`per_host` / `perHost`	`HashMap<String, u32>`	Ready forks per machine.
`peak_parallel` / `peakParallel`	`HashMap<String, u32>`	Most forks starting at once per machine.

`ForkBatchResult` record#

A finished batch. Every fork and the summary (ForkBatch.collect).

Returned by ForkBatch.collect.

Field	Type	Default	Description
`items`	`Vec<ForkBatchItem>`		The forks, by index.
`summary`	`ForkBatchSummary`		The summary.

All items#

10 items, across this page and its subpages, grouped by page (each item's section is on its page). Methods are listed on their object.

Batched forks: ForkBatch, ForkBatchEvent, ForkBatchItem, ForkBatchPlacement, ForkBatchResult, ForkBatchSummary, ForkGroup, ForkManyOptions, SnapshotFallbackOptions, SnapshotSyncProgress

Batched forks

Batch methods#

Sandboxes.fork_many#

Sandboxes.fork_groups#

Sandboxes.publish_checkpoint#

ForkBatch#

ForkBatch.collect#

ForkBatch.next#

ForkManyOptions record#

ForkGroup record#

SnapshotFallbackOptions record#

ForkBatchEvent enum#

ForkBatchItem record#

ForkBatchPlacement record#

SnapshotSyncProgress record#

ForkBatchSummary record#

ForkBatchResult record#