tur/effects
standard algebraic effects for IO, logging, and randomness.
Since: Phase 19
IO
(IO :nil)
base effect for all I/O operations.
nil
(defeffect Write [s :cstr] :nil ^extends IO)
Since: ET4
FS
(FS :nil)
capability tag for file-system access (fs, path, tmpfile).
nil (never performed; used only as a #fx{FS} row annotation)
(defn read-config [p : cstr] #fx{FS} : cstr ...)
Since: stdlib-effect-rows
Net
(Net :nil)
capability tag for network access (net, async_socket, httpd).
nil (never performed; used only as a #fx{Net} row annotation)
(defn http-get [url : cstr] #fx{Net} : cstr ...)
Since: stdlib-effect-rows
Proc
(Proc :nil)
capability tag for process/environment access (process, env).
nil (never performed; used only as a #fx{Proc} row annotation)
(defn spawn [cmd : cstr] #fx{Proc} : int ...)
Since: stdlib-effect-rows
Rand
(Rand :nil)
capability tag for non-deterministic randomness (random).
nil (never performed; used only as a #fx{Rand} row annotation)
(defn rand-u64 [] #fx{Rand} : int ...)
Since: stdlib-effect-rows
Write
(Write [s :cstr] :nil)
declare an effect that writes a string to the environment.
| s | the string to write |
nil
(perform (Write "hello")) ; => nil
Since: Phase 19
Fail
(Fail [msg :cstr] :nil))
declare an effect that signals a failure with a message string.
| msg | the failure message |
nil
(perform (Fail "something went wrong")) ; => nil
Since: Phase 19
Read
(Read :int)
declare an effect that requests an integer value from the environment.
int -- the integer supplied by the enclosing handler
(perform (Read)) ; => 42
Since: Phase 19
GetEnv
(GetEnv [key :cstr] :cstr))
declare an effect that looks up a named environment variable.
| key | the environment variable name to look up |
cstr -- the value of the variable, or nil if absent
(perform (GetEnv "HOME")) ; => "/home/user"
Since: Phase 19
with-write
(with-write [body])
handle the Write effect by printing to stdout via println.
| body | the expression whose Write effects are handled |
the return value of body
(with-write (perform (Write "hello"))) ; prints "hello"
Since: Phase 19
with-fail-panic
(with-fail-panic [body])
handle the Fail effect by panicking with the message.
| body | the expression whose Fail effects are handled |
the return value of body, or panics on Fail
(with-fail-panic (perform (Fail "oops"))) ; panics with "oops"
Since: Phase 19
with-getenv
(with-getenv [body])
handle the GetEnv effect by delegating to C getenv(3).
| body | the expression whose GetEnv effects are handled |
the return value of body
(with-getenv (perform (GetEnv "PATH"))) ; => "/usr/bin:..."
Since: Phase 19
read-int-console
(read-int-console)
read a single integer from stdin via scanf.
int -- the integer read from stdin
(read-int-console) ; => 7
Since: Phase 19
with-read-console
(with-read-console [body])
handle the Read effect by reading an integer from stdin.
| body | the expression whose Read effects are handled |
the return value of body
(with-read-console (perform (Read))) ; reads integer from stdin
Since: Phase 19
Log
(Log [level :cstr msg :cstr] :nil))
declare an effect that emits a leveled log message.
| level | severity label (e.g. "info", "warn", "error") | |
| msg | the message text |
nil
(perform (Log "info" "server started")) ; => nil
Since: Phase 19
with-stderr-log
(with-stderr-log [body])
handle the Log effect by printing all messages to stdout.
| body | the expression whose Log effects are handled |
the return value of body
(with-stderr-log (perform (Log "warn" "low memory"))) ; prints "low memory"
Since: Phase 19
with-silent-log
(with-silent-log [body])
handle the Log effect by suppressing all log output.
| body | the expression whose Log effects are handled |
the return value of body
(with-silent-log (perform (Log "debug" "ignored"))) ; no output
Since: Phase 19
Abort
(Abort [msg :cstr] :int))
declare an effect that signals an unrecoverable abort.
| msg | the abort message |
int (never actually returned; the handler must not resume k)
(perform (Abort "fatal error")) ; handler should not resume
Since: Phase 19
with-abort-panic
(with-abort-panic [body])
handle the Abort effect by panicking with the message.
| body | the expression whose Abort effects are handled |
the return value of body, or panics on Abort
(with-abort-panic (perform (Abort "fatal"))) ; panics with "fatal"
Since: Phase 19
Async
(Async [thunk :ptr<void>] :ptr<void>))
declare an effect that spawns an async computation and returns a Future.
| thunk | a zero-argument function pointer to run asynchronously |
ptr<void> -- a Future that can be passed to Await
(perform (Async my-thunk)) ; => future-ptr
Since: Phase T25
Await
(Await [future :ptr<void>] :int))
declare an effect that awaits a Future and returns its resolved value.
| future | a Future pointer previously returned by Async |
int -- the resolved integer value of the future
(perform (Await my-future)) ; => 42
Since: Phase T25
with-async
(with-async [body])
handle the Async effect by running the thunk and resuming with its result.
| body | the expression whose Async effects are handled |
the return value of body
(with-async (perform (Async my-thunk))) ; runs thunk inline
Since: Phase T25
with-await
(with-await [body])
handle the Await effect by blocking until the future resolves.
| body | the expression whose Await effects are handled |
the return value of body
(with-await (perform (Await my-future))) ; => resolved value
Since: Phase T25