Skip to content
Kalandra Documentation

HOWTO guides

CPU parallelism

Spawn typed tasks and keep their lifetimes structured.

Use CPU tasks when independent work can run concurrently. You will need the ordinary CPU compilation commands from getting started. spawn starts a task, await obtains its result, and a parallel scope keeps the tasks' lifetimes within its block. Declare and handle or propagate TaskError for execution failures.

Start independent work before awaiting

kalandra
fn double(value: int) -> int:
  value * 2

fn main() -> int ! TaskError:
  try parallel:
    left = spawn double(10)
    right = spawn double(11)
    a = try await left
    b = try await right
    a + b

This returns 42. Both tasks are created before either is awaited, so the scheduler can run them concurrently. spawn followed immediately by await is useful for placement or boundaries, but a sequence of such pairs does not expose the same independent overlap.

A parallel scope owns its children

A scope waits for its children to finish before exiting, including when work fails. A waiting task does not occupy a worker thread just to wait. Repeated awaits reuse the completed result; they do not rerun the work.

Tasks can read supported captured values. Parent-provided arrays are read-only to the task, and the parent cannot write that storage while unfinished task readers may still use it. Await every reader before writing, or create an independent copy. Reassigning the parent's local array name does not change the array a task already received.

Map an array in parallel

kalandra
fn main() -> [int] ! TaskError:
  factor = 2
  try parallelMap([1, 2, 3], fn(value: int): value * factor)

This returns [2, 4, 6]. parallelMap returns results in input order and can change the element type under the supported callback rules. map remains sequential. Scheduling a map call with spawn creates a task containing one sequential mapping loop; it does not turn each element into an independent task.

Workers and resource limits

Generated CPU programs use a limited pool of worker threads. The default is based on the host and capped at eight; KALANDRA_WORKERS accepts 1 through 64. The runtime also limits queued work and task storage. It can reject work with TaskError.AdmissionRejected when those limits are reached. Tiny callbacks may cost more to schedule than to execute, so measure your actual workload.

bash
KALANDRA_WORKERS=4 ./program

The environment setting applies when running the compiled program; the command above uses a macOS or Linux shell.

Cancellation is cooperative: a task stops at a cancellation check rather than being killed at an arbitrary instruction. Completed writes are not rolled back. When several tasks fail concurrently, the observed failure is not guaranteed to be the same each run. GPU placement is explicit and supports a narrower set of operations than CPU execution.