combinator

type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }

Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.

type struct Name {
    field: Type;
    method(&this) -> Ret { ... }
}

A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.

type struct Futures {}

Constructors for the combinators above.

static name(param: Type) -> Ret { ... }

A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.

static Futures::join<A, B, OA, OB>(a: A, b: B) -> Join<A, B, OA, OB>
where A: Future<OA>, B: Future<OB>

Run a and b concurrently; complete with both values.

type parameter A

where A: Future

type parameter B

where B: Future

type parameter A

where A: Future

type parameter B

where B: Future

type struct Join<A, B, OA, OB> {
    a: A;
    b: B;
    a_out: Option<OA>;
    b_out: Option<OB>;
    a_done: boolean;
    b_done: boolean;
}

Runs two futures concurrently and completes with both results once both have finished. Each child is polled only until it completes; its value is parked in an Option until the other one catches up.

where T: Ord + Clone, U: Hash

Constrains generic parameters to types that implement the listed traits, which is what makes those traits' methods callable on T. Bounds on one parameter join with +; parameters separate with ,. A where on a single method narrows the type's parameter for that method only.

type trait Future {
    type Output;
    poll(mut &this, cx: Context*) -> Poll<This::Output>;
}

An asynchronous computation. poll drives it one step: Ready(v) when the value is available, Pending when it is not yet (the future has arranged, via cx's waker, to be polled again later).

static Futures::try_join<A, B, T1, T2, E>(a: A, b: B) -> TryJoin<A, B, T1, T2, E>
where A: Future<Result<T1, E>>, B: Future<Result<T2, E>>

Run a and b concurrently; complete with both values, or with the first error either reports, dropping the sibling.

type parameter A

where A: Future

type parameter B

where B: Future

type struct TryJoin<A, B, T1, T2, E> {
    a: A;
    b: B;
    a_out: Option<T1>;
    b_out: Option<T2>;
    a_done: boolean;
    b_done: boolean;
    done: boolean;
}

Runs two fallible futures concurrently and completes with both values, or with the FIRST error either of them reports.

type enum Result<T, E> {
    Ok(T);
    Err(E);
}

Result: a value that may be an error.

static Futures::select<A, B, OA, OB>(a: A, b: B) -> Select<A, B, OA, OB>
where A: Future<OA>, B: Future<OB>

Run a and b concurrently; complete as soon as either does, dropping the other.

type parameter A

where A: Future

type parameter B

where B: Future

type struct Select<A, B, OA, OB> {
    a: A;
    b: B;
    done: boolean;
}

Runs two futures concurrently and completes as soon as EITHER finishes, reporting which one it was. The loser is dropped with this future, which cancels it.

static Futures::timeout<F, O>(dur: Duration, fut: F) -> Timeout<F, O>
where F: Future<O>

Run fut with a deadline dur from now.

type parameter F

where F: Future

type struct Duration {
    secs: u64;
    nanos: u32;
}

A length of time: whole secs plus a sub-second nanos remainder (0 <= nanos < 1_000_000_000). POD; copy-by-value, no drop.

type parameter F

where F: Future

type struct Timeout<F, O> {
    fut: F;
    sleep: Sleep;
    done: boolean;
}

Runs a future with a deadline: Ok(value) if it finishes in time, otherwise Err(Elapsed).

static Futures::timeout_at<F, O>(deadline: Instant, fut: F) -> Timeout<F, O>
where F: Future<O>

Run fut with an absolute deadline.

type struct Instant {
    secs: i64;
    nanos: i64;
}

A measurement of the monotonic clock. Opaque: the fields are the raw timespec, meaningful only relative to another Instant. POD.

type parameter F

where F: Future

type struct Join<A, B, OA, OB> {
    a: A;
    b: B;
    a_out: Option<OA>;
    b_out: Option<OB>;
    a_done: boolean;
    b_done: boolean;
}

Runs two futures concurrently and completes with both results once both have finished. Each child is polled only until it completes; its value is parked in an Option until the other one catches up.

type enum Option<T> {
    Some(T);
    None;
}

Option: a value that may be absent.

primitive boolean

true / false. Not interchangeable with integers. 1 byte.

type struct TryJoin<A, B, T1, T2, E> {
    a: A;
    b: B;
    a_out: Option<T1>;
    b_out: Option<T2>;
    a_done: boolean;
    b_done: boolean;
    done: boolean;
}

Runs two fallible futures concurrently and completes with both values, or with the FIRST error either of them reports.

TryJoin.done: boolean

Set by BOTH completion paths. a_done && b_done cannot stand in for it: an error completes this future with the other side still unfinished, so without a separate flag a later poll would drive a child again after this future had already reported.

type struct Select<A, B, OA, OB> {
    a: A;
    b: B;
    done: boolean;
}

Runs two futures concurrently and completes as soon as EITHER finishes, reporting which one it was. The loser is dropped with this future, which cancels it.

type enum Name {
    Unit,
    Payload(T),
    Named { x: i32 },
}

An algebraic data type. Variants may be bare or carry a tuple or struct payload, and a match on an enum must cover every variant. Name::Variant names a variant; methods are added with implement enum Name { ... }.

type enum Selected<L, R> {
    First(L);
    Second(R);
}

Which side of a Select finished first.

type struct Timeout<F, O> {
    fut: F;
    sleep: Sleep;
    done: boolean;
}

Runs a future with a deadline: Ok(value) if it finishes in time, otherwise Err(Elapsed).

type struct Sleep {
    deadline: i64;
    id: u64;
    rt: Reactor*;
}

A future that completes once the monotonic clock reaches its deadline.

type struct Elapsed {
    deadline: i64;
}

A Timeout expired before the operation it was timing finished.

primitive i64

64-bit signed integer.

type struct Elapsed {
    deadline: i64;
}

A Timeout expired before the operation it was timing finished.

Elapsed::deadline_nanos(&this) -> i64

The monotonic-nanosecond deadline that was missed.

&this
mut &this
this

The receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).

namespace std;

std: the Cryo standard library.

namespace std::future;

std::future: stackless async foundations — Future, Poll, Context, Waker, and the drivers that poll them.

namespace std::future::combinator;

std::future::combinator: running futures against each other — Join, TryJoin, Select, and Timeout.

Join::poll(mut &this, cx: Context*) -> Poll<(OA, OB)>

via trait Future

type struct Context {
    waker: Waker;
}

The context threaded through a poll call. Holds the Waker a future registers when it returns Pending. Passed by pointer down the poll tree, matching the stdlib convention of moving aggregates by pointer.

type struct Futures {}

Constructors for the combinators above.

async function name(param: Type) -> T { ... }

Compiles the function into a stackless state machine. Calling it builds a future whose output is the declared return type; nothing runs until that future is polled. Allowed on free functions, methods, and trait methods.

function name<T>(param: Type) -> Ret { ... }

Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.

static Futures::join<A, B, OA, OB>(a: A, b: B) -> Join<A, B, OA, OB>
where A: Future<OA>, B: Future<OB>

Run a and b concurrently; complete with both values.

static Futures::try_join<A, B, T1, T2, E>(a: A, b: B) -> TryJoin<A, B, T1, T2, E>
where A: Future<Result<T1, E>>, B: Future<Result<T2, E>>

Run a and b concurrently; complete with both values, or with the first error either reports, dropping the sibling.

static Futures::select<A, B, OA, OB>(a: A, b: B) -> Select<A, B, OA, OB>
where A: Future<OA>, B: Future<OB>

Run a and b concurrently; complete as soon as either does, dropping the other.

static Futures::timeout<F, O>(dur: Duration, fut: F) -> Timeout<F, O>
where F: Future<O>

Run fut with a deadline dur from now.

static Futures::timeout_at<F, O>(deadline: Instant, fut: F) -> Timeout<F, O>
where F: Future<O>

Run fut with an absolute deadline.

TryJoin.done: boolean

Set by BOTH completion paths. a_done && b_done cannot stand in for it: an error completes this future with the other side still unfinished, so without a separate flag a later poll would drive a child again after this future had already reported.

Instant::as_nanos(&this) -> i64

This reading as raw monotonic nanoseconds. The absolute value is meaningful only relative to another Instant - it counts from an unspecified epoch (typically system boot) - so use it for lightweight elapsed-time math where the difference of two readings is all that matters and carrying a Duration would be overkill.

Elapsed::deadline_nanos(&this) -> i64

The monotonic-nanosecond deadline that was missed.

type trait Drop {
    drop(mut &this) -> void;
}

Drop: explicit destructor.

type struct Ready<T> {
    value: Option<T>;
}

A future that is already complete: the first poll returns Ready(value). The value is held in an Option and moved out on completion, so polling a Ready a second time is a contract violation (it panics) rather than a double-move.

implement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }

Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.

type trait Name : Base {
    method(&this, other: &This) -> Ret;
}

Names a set of methods a type may implement. Inside the body This is the implementing type; methods may carry default bodies, and a trait may require a base trait (type trait Ord : Eq). Generic code asks for a trait with where T: Name.

implement trait Trait for Type { ... }

Names the type a trait implementation is for. The block that follows supplies the bodies the trait requires.

type enum Selected<L, R> {
    First(L);
    Second(R);
}

Which side of a Select finished first.