tur/capability

(defopaque FileSystem : ptr<void>)

opaque handle to a FileSystem capability vtable.

Built by make-FileSystem (or stdlib/io.tur's Real-FileSystem); released by the matching *-free.

Since: Phase 16

(defopaque Logger : ptr<void>)

opaque handle to a Logger capability vtable (debug/info/warn/error).

Since: Phase 16

(defopaque Random : ptr<void>)

opaque handle to a Random capability vtable (next-int/next-float).

Since: Phase 16

(make-FileSystem [read_fn : (c-fn [cstr ptr<u8> i32 ptr<i32>] i32) write_fn : (c-fn [cstr ptr<u8> i32] i32) delete_fn : (c-fn [cstr] i32) list_fn : (c-fn [cstr ptr<void> i32 ptr<i32>] i32)] : FileSystem)

construct a FileSystem capability from four C callbacks.

The callbacks are bare C-ABI function pointers with the vtable's own signatures, so a defn spelled with i32 / ptr<u8> / ptr<i32> parameters (or a C function) can be passed directly.

(def fs (make-FileSystem my-read my-write my-delete my-list))

Since: Phase 16

(FileSystem-free [fs : FileSystem] : nil)

free a FileSystem capability allocated by make-FileSystem.

(FileSystem-free fs)

Since: Phase 16

(make-Logger [debug_fn : (c-fn [cstr] nil) info_fn : (c-fn [cstr] nil) warn_fn : (c-fn [cstr] nil) error_fn : (c-fn [cstr] nil)] : Logger)

construct a Logger capability from four C callbacks (debug/info/warn/error).

(def lg (make-Logger on-debug on-info on-warn on-error))

Since: Phase 16

(Logger-free [log : Logger] : nil)

free a Logger capability allocated by make-Logger.

(Logger-free lg)

Since: Phase 16

(make-Random [next_int_fn : (c-fn [i32 i32] i32) next_float_fn : (c-fn [] i32)] : Random)

construct a Random capability from two C callbacks.

(def rng (make-Random my-next-int my-next-float))

Since: Phase 16

(Random-free [rng : Random] : nil)

free a Random capability allocated by make-Random.

(Random-free rng)

Since: Phase 16

(make-Time [now_fn : (c-fn [] i64) sleep_fn : (c-fn [i32] nil)] : Time)

construct a Time capability from two C callbacks.

The handle type is the time module's Time, so a Real-Time or Mock-Time handle and one built here are interchangeable.

(def clock (make-Time my-now my-sleep))

Since: Phase 16

(Time-free [t : Time] : nil)

free a Time capability allocated by make-Time.

(Time-free clock)

Since: Phase 16

(with-capability [bindings & body])

bind capabilities and evaluate body with them in scope.

Takes a let-shaped binding vector, like every other with-* form.

(with-capability [fs (make-FileSystem r w d l)] (fs-delete fs "data.txt"))

Since: Phase 16

(default-capability [type_name])

return the default implementation for a capability type (currently always nil).

Since: Phase 16

(fs-read [fs : FileSystem path : cstr buf : ptr<void> buf_len : int] : int)

call read_file on a FileSystem capability.

(fs-read fs "data.txt" buf 64)  ; => 0

Since: Phase 16

(fs-write [fs : FileSystem path : cstr data : ptr<void> data_len : int] : int)

call write_file on a FileSystem capability.

(fs-write fs "data.txt" buf 5)  ; => 0

Since: Phase 16

(fs-delete [fs : FileSystem path : cstr] : int)

call delete on a FileSystem capability.

(fs-delete fs "data.txt")  ; => 0

Since: Phase 16

(fs-list [fs : FileSystem path : cstr entries : ptr<void> max_entries : int] : int)

call list on a FileSystem capability.

(fs-list fs "." entries 16)  ; => 0

Since: Phase 16

(log-debug [log : Logger msg : cstr] : nil)

emit a debug-level log message via a Logger capability.

(log-debug lg "starting")

Since: Phase 16

(log-info [log : Logger msg : cstr] : nil)

emit an info-level log message via a Logger capability.

(log-info lg "ready")

Since: Phase 16

(log-warn [log : Logger msg : cstr] : nil)

emit a warning-level log message via a Logger capability.

(log-warn lg "disk nearly full")

Since: Phase 16

(log-error [log : Logger msg : cstr] : nil)

emit an error-level log message via a Logger capability.

(log-error lg "write failed")

Since: Phase 16

(rng-next-int [rng : Random min : int max : int] : int)

return a random integer in [min, max] from a Random capability.

(rng-next-int rng 1 6)  ; => 4

Since: Phase 16

(rng-next-float [rng : Random] : int)

return a random pseudo-float in [0, 10000) from a Random capability.

(rng-next-float rng)  ; => 2500

Since: Phase 16

(time-now [t : Time] : int)

return the current time in milliseconds since epoch from a Time capability.

(time-now clock)  ; => 1000

Since: Phase 16

(time-sleep [t : Time ms : int] : nil)

sleep for ms milliseconds via a Time capability.

(time-sleep clock 250)

Since: Phase 16