tur/future

(defopaque Promise :ptr<void> :linear)

(defopaque Future :ptr<void> :affine)

(future-cell-new :Promise)

allocate and initialise a shared FutureCell (mutex, condvar, unset).

Since: Phase T20-C

(future-cell-free [cell :Promise] :nil)

destroy the mutex/condvar and free a FutureCell.

Since: Phase T20-C

(promise-new :Promise)

allocate a new unsettled Promise/Future shared cell.

(def p (promise-new))
(promise-fulfill p 42)

Since: Phase T20-C

(promise-of-cell [cell :Promise] :Promise)

return the Promise handle for a FutureCell (identity; for API symmetry).

Since: Phase T20-C

(future-of-cell [cell :Promise] :Future)

return the Future handle for a FutureCell (identity; for API symmetry).

Since: Phase T20-C

(future-handle [^borrow p :Promise] :Future)

borrow a Promise and derive a Future over the same cell.

Unlike future-of-cell (which *transfers* ownership, consuming the Promise), future-handle borrows the Promise (^borrow) and bumps the shared cell's reference count, so the producer keeps the Promise to settle while the consumer holds the returned Future to read and free. The cell is torn down only when both references are dropped (by promise-fulfill/-fail/-free on the Promise side and future-free on the Future side).

(let [p (promise-new)]
  (let [f (future-handle p)]
    (promise-fulfill p 42)      ; consumes p, settles
    (future-get f)              ; read via f
    (future-free f)))           ; consumes f, frees the cell

Since: stdlib-linearity-affinity (Future aliasing fix)

(promise-pair [cell])

expand to a (Promise Future) pair list from a single shared cell.

Since: Phase T20-C

(promise-fulfill [p :Promise v :int] :nil)

settle a promise with a successful value; wakes all future waiters.

Since: Phase T20-C

(promise-fail [p :Promise e :int] :nil)

settle a promise with an error code; wakes all future waiters.

Since: Phase T20-C

(promise-free [p :Promise] :nil)

free a promise and its shared FutureCell.

Since: Phase T20-C

(future-done? [^borrow f :Future] :bool)

non-blocking check: return true if the future has been settled.

Since: Phase T20-C

(future-get [^borrow f :Future] :ptr<void>)

block until the future is settled; return a heap-allocated Result struct.

(def result (future-get f))

Since: Phase T20-C

(future-free [f :Future] :nil)

free a future and its shared FutureCell.

Since: Phase T20-C

(future-of [v :int] :Future)

create a pre-fulfilled future holding value v.

(def f (future-of 42))  ; immediately done

Since: Phase T20-C

(future-error-of [e :int] :Future)

create a pre-rejected future with error code e.

Since: Phase T20-C

(future-cancel [^borrow f :Future] :nil)

cancel a future if not yet settled; sets error code -2 (TUR_FUTURE_CANCELLED).

Since: Phase T20-C

(future-cancelled? [^borrow f :Future] :bool)

return true if the future was cancelled (exn == -2).

Since: Phase T20-C

(future-map [^borrow f :Future ^fat fn :(fn [int] int)] :Future)

map fn over a fulfilled future value; propagate rejection unchanged.

Since: Phase T20-C

(future-then [^borrow f :Future ^fat fn :(fn [int] Future)] :Future)

flat-map fn over a future; fn must return a new Future ptr<void>.

Since: Phase T20-C

(future-race [^borrow fa :Future ^borrow fb :Future] :Future)

race two futures; return a new future settled by whichever finishes first.

Since: Phase T20-C

(future-all2 [^borrow fa :Future ^borrow fb :Future] :Future)

await both futures; settle ok with fa's value only if both succeed.

Since: Phase T20-C

(future-any2 [^borrow fa :Future ^borrow fb :Future] :Future)

return a future settled by the first fulfilled future; both rejecting yields fb's error.

Since: Phase T20-C

(future-join [^borrow fa :Future ^borrow fb :Future] :Future)

await both futures and produce a new future holding a Tuple2 of their values.

Since: Phase T20-C

(tuple-first [tup :ptr<void>] :int)

read the first element of a Tuple2 returned by future-join.

Since: Phase T20-C

(tuple-second [tup :ptr<void>] :int)

read the second element of a Tuple2 returned by future-join.

Since: Phase T20-C

(tuple-free [tup :ptr<void>] :nil)

free a Tuple2 allocated by future-join.

Since: Phase T20-C

(promise-new-pair :Promise)

allocate a new unsettled Promise/Future shared cell (alias for promise-new).

Since: Phase T20-C

(future-race-n [futures :ptr<void> n :int] :Future)

race an array of n futures; return a new future settled by the first to finish.

Since: Phase T20-C

(future-all-n [futures :ptr<void> n :int] :Future)

await all n futures; settle ok (value 0) only if every future succeeds.

Since: Phase T20-C

(future-any-n [futures :ptr<void> n :int] :Future)

return a future settled by the first successfully fulfilled future in the array.

Since: Phase T20-C

(future-timeout-thread [raw :ptr<void>] :ptr<void>)

pthread body for future-timeout. INTERNAL.

(future-with-timeout-tfn [raw :ptr<void>] :ptr<void>)

pthread body for the timeout half of future-with-timeout. INTERNAL.

(future-with-timeout-wfn [raw :ptr<void>] :ptr<void>)

pthread body for the wait half of future-with-timeout. INTERNAL.

(future-timeout [ms :int] :Future)

create a future that settles with error -1 after ms milliseconds.

(def t (future-timeout 5000))  ; rejects after 5 seconds

Since: Phase T20-C

(future-with-timeout [^borrow f :Future ms :int] :Future)

race a future against a timeout of ms milliseconds.

Since: Phase T20-C