rontolisp Package Functions
The rontolisp package provides implementation-specific functions that are
not part of Common Lisp. Reference them with the rontolisp: qualifier (or
unqualified after (in-package rontolisp)); see Packages for the
package system. Each name below links to its own page.
| Function | Example | Result |
|---|---|---|
rontolisp:version | (rontolisp:version) | a property list of build info (:version, :build-timestamp, :git-commit, :git-branch) |
rontolisp:random-bytes | (rontolisp:random-bytes 16) | a vector of cryptographically strong random bytes (SecureRandom / WASI random_get) |
rontolisp:unix-time | (rontolisp:unix-time) | the wall clock as two values: seconds since the Unix epoch and the nanoseconds within that second |
rontolisp:bfloat16-bits | (rontolisp:bfloat16-bits 1.0) | the bfloat16 bit pattern of a real, rounded to nearest even (0-65535) |
rontolisp:bits-bfloat16 | (rontolisp:bits-bfloat16 16256) | the float a bfloat16 bit pattern encodes; exact for all 65536 patterns |
rontolisp:float16-bits | (rontolisp:float16-bits 1.0) | the IEEE binary16 (f16) bit pattern of a real, rounded to nearest even (0-65535) |
rontolisp:bits-float16 | (rontolisp:bits-float16 15360) | the float an f16 bit pattern encodes |
rontolisp:widen-float-bits | (rontolisp:widen-float-bits bits :float16 dst) | widen a packed (unsigned-byte 16) vector of f16/bfloat16 bit patterns into a packed float array, in bulk |
rontolisp:narrow-float-bits | (rontolisp:narrow-float-bits src :bfloat16 dst) | narrow a packed float array into a packed (unsigned-byte 16) vector of f16/bfloat16 bit patterns, in bulk |
rontolisp:quantize | (rontolisp:quantize w 'q8-0) | a packed float matrix as a block-quantized weight matrix (ggml's Q8_0: 32-element blocks, one binary16 scale and 32 int8 quants), the operand vec:matvec runs its integer-dot GEMV over; interpreter and JVM |
rontolisp:dequantize | (rontolisp:dequantize m 'single-float) | a quantized matrix expanded into a fresh packed float array of the element type named |
rontolisp:make-quantized-matrix | (rontolisp:make-quantized-matrix 'q8-0 '(rows cols)) | an all-zero quantized matrix, the destination read-sequence fills with a Q8_0 tensor's bytes |
rontolisp:quantized-rows | (rontolisp:quantized-rows m '(3 1)) | a fresh quantized matrix of the rows named, block for block -- an array copy a row, no dequantizing; this type's subseq and linalg:take-rows |
rontolisp:quantized-matrix-p | (rontolisp:quantized-matrix-p m) | t if the value is a quantized matrix (also (typep m 'rontolisp:quantized-matrix)) |
rontolisp:octets-to-string | (rontolisp:octets-to-string #8@(72 105)) | decode a packed (unsigned-byte 8) vector as the UTF-8 text its bytes spell; total and lenient |
rontolisp:string-to-octets | (rontolisp:string-to-octets "Hi") | encode a string as UTF-8, as a packed (unsigned-byte 8) vector |
rontolisp:make-mutex | (rontolisp:make-mutex) | a fresh mutual-exclusion lock, as an opaque handle (real on the interpreter and the JVM, a no-op on WASM) |
rontolisp:mutex-acquire | (rontolisp:mutex-acquire m) | block until this thread holds the mutex; returns it (prefer rontolisp:with-mutex) |
rontolisp:mutex-release | (rontolisp:mutex-release m) | release one acquisition of the mutex; returns it |
rontolisp:make-thread | (rontolisp:make-thread fn bindings) | spawn a virtual thread running the zero-argument function, with optional (symbol . value) dynamic bindings established in it; returns an opaque handle (interpreter and JVM; the WASM shims signal) |
rontolisp:join-thread | (rontolisp:join-thread th) | wait for the thread and yield its function's value; an error it died on is re-signaled here |
rontolisp:threadp | (rontolisp:threadp v) | t if the value is a thread handle |
rontolisp:thread-alive-p | (rontolisp:thread-alive-p th) | t while the thread is still running (nil after a join) |
rontolisp:destroy-thread | (rontolisp:destroy-thread th) | interrupt the thread; returns the handle |
rontolisp:current-thread | (rontolisp:current-thread) | the calling thread's own handle, eq-stable per thread (works for any thread, not only make-thread spawns) |
rontolisp:fetch | (rontolisp:fetch "http://example.com/") | start an HTTP request asynchronously; returns a future |
rontolisp:futurep | (rontolisp:futurep v) | t if the value is a future (as returned by calling an async-defun function, rontolisp:fetch, rontolisp:stream-read, ...) |
rontolisp:streamp | (rontolisp:streamp v) | t if the value is an asynchronous stream (a different predicate from cl:streamp, which answers file streams) |
rontolisp:make-stream | (rontolisp:make-stream) | create a fresh open asynchronous stream; one value owns both the read and the write end |
rontolisp:stream-read | (rontolisp:stream-read s) | a future settling to the stream's next chunk, or nil at end of stream |
rontolisp:stream-write | (rontolisp:stream-write s "chunk") | append a chunk (never nil); returns a future that settles when the stream accepted it |
rontolisp:stream-close | (rontolisp:stream-close s) | close the write end; buffered chunks stay readable, then reads observe end of stream |
rontolisp:read-all | (rontolisp:read-all s) | a future settling to the remaining chunks drained into one string (octet chunks -- every HTTP body stream's -- UTF-8 decoded) |
rontolisp:wait-for | (rontolisp:wait-for 100) | a future settling to nil after the given milliseconds; the async counterpart of cl:sleep |
rontolisp:then | (rontolisp:then f (lambda (v) (* 2 v))) | attach a transform to a future as a value; returns a fresh future on the success channel (JavaScript .then) |
rontolisp:then* | (rontolisp:then* f #'1+ #'1+) | variadic chain sugar for rontolisp:then; each function receives the previous stage's flattened value |
rontolisp:catch | (rontolisp:catch f (lambda (c) :fallback)) | attach an error fallback to a future as a value (JavaScript .catch); distinct from cl:catch/throw |
rontolisp:finally | (rontolisp:finally f (lambda () (cleanup))) | run a cleanup thunk on both success and error channels; the original outcome carries through |
rontolisp:http-handler | (rontolisp:http-handler 'handle 8080) | serve HTTP requests with a handler function taking the Clack environment plist and returning (status headers body) (a blocking server; a wasi:http component under --component) |
rontolisp:json-parse | (rontolisp:json-parse "{\"n\": 1}") | parse a JSON string (jzon-compatible): objects become hash tables with string keys, arrays vectors |
rontolisp:json-stringify | (rontolisp:json-stringify (vector 1 2)) | serialize a value to a JSON string (hash tables and CLOS instances become objects, lists and vectors arrays) |
rontolisp:json-span | (rontolisp:json-span "{\"a\": [1]}" "a" 0) | the byte offsets of the value a path of keys and indexes leads to in a JSON document (a string, octets, or bytes of linear memory), the document checked as json-parse checks it; where an edit splices |
rontolisp:json-value | (rontolisp:json-value "{\"a\": [1]}" "a" 0) | the value at a path of a JSON document as json-parse makes it, and whether there is one; nothing else of the document becomes Lisp values |
rontolisp:plist-hash-table | (rontolisp:plist-hash-table (list :n 1)) | build a hash table from a property list (subset of alexandria:plist-hash-table); handy for JSON objects |
rontolisp:hash-table-plist | (rontolisp:hash-table-plist h) | property list of a hash table's pairs (subset of alexandria:hash-table-plist) |
rontolisp:alist-hash-table | (rontolisp:alist-hash-table al) | build a hash table from an association list (subset of alexandria:alist-hash-table) |
rontolisp:hash-table-alist | (rontolisp:hash-table-alist h) | association list of a hash table's pairs (subset of alexandria:hash-table-alist) |
rontolisp:alist-plist | (rontolisp:alist-plist al) | property list with an association list's keys and values, order preserved (subset of alexandria:alist-plist) |
rontolisp:plist-alist | (rontolisp:plist-alist pl) | association list with a property list's keys and values, order preserved (subset of alexandria:plist-alist) |
rontolisp:starlark-call | (rontolisp:starlark-call f 1 2) | call a function value of the experimental Starlark front end -- a def, a lambda, a built-in, a method -- with positional arguments |
rontolisp:tcp-connect | (rontolisp:tcp-connect "127.0.0.1" 7777) | open a blocking TCP connection; returns a bidirectional stream handle |
rontolisp:tcp-listen | (rontolisp:tcp-listen 7777), (rontolisp:tcp-listen 0 "127.0.0.1") | bind a listening TCP socket and return a listener handle; port 0 picks a free ephemeral port |
rontolisp:tcp-accept | (rontolisp:tcp-accept listener) | wait for a client connection (blocking); returns a bidirectional stream handle |
rontolisp:tcp-local-port | (rontolisp:tcp-local-port listener) | the local port a listener or socket is actually bound to |
rontolisp:tcp-local-address | (rontolisp:tcp-local-address listener) | the local IP address a listener or socket is bound to, as a string |
rontolisp:tcp-peer-address | (rontolisp:tcp-peer-address sock) | the remote IP address of a connected socket, as a string |
rontolisp:tcp-peer-port | (rontolisp:tcp-peer-port sock) | the remote port of a connected socket |
rontolisp:tcp-set-timeout | (rontolisp:tcp-set-timeout sock 5000) | set a read deadline in milliseconds (nil clears); a timed-out read signals a catchable error |
rontolisp:tls-connect | (rontolisp:tls-connect "example.com" 443) | open an encrypted (TLS) client connection; returns the same kind of stream handle as tcp-connect |
rontolisp:tls-listen | (rontolisp:tls-listen "server.p12" "changeit" 8443) | bind an encrypted listening socket from a PKCS12 keystore; accept with tcp-accept |
rontolisp:tls-listen-pem | (rontolisp:tls-listen-pem "cert.pem" "key.pem" 8443) | bind an encrypted listening socket from PEM certificate/key files |
rontolisp:tls-upgrade | (rontolisp:tls-upgrade sock "example.com") | wrap an already-connected stream handle in TLS as a client; returns a new stream handle |
rontolisp:wasm-export | (rontolisp:wasm-export 'fact :params '(:int) :returns :int) | mark a defun as host-callable when compiling to a WASM core module |
rontolisp:jvm-export | (rontolisp:jvm-export 'fact :params '(:s64) :returns :s64) | declare a typed, Java-callable static method for a defun when compiling to a JVM class |
rontolisp:wasm-import | (rontolisp:wasm-import 'add :from "host" :params '(:int :int) :returns :int) | declare a host function callable from Lisp when compiling to a WASM core module |
rontolisp:wit-export | (rontolisp:wit-export "greeter.wit" :world greeter) | declare that the program implements a WIT world: its exports are checked against the program's defuns, and their types come from the WIT |
rontolisp:wit-import | (rontolisp:wit-import "store.wit" :interface "wasi:keyvalue/store@0.2.0" :package kv) | declare that the program calls a WIT interface: every function it declares is bound as an ordinary Lisp function (kv:bucket-get), against a provider on the interpreter/JVM, a WASM import on Preview 1, and a canon lowered component-model import under --component, where the host is the provider |
rontolisp:wit-provide | (rontolisp:wit-provide "wasi:keyvalue/store@0.2.0" #'my-store) | bind the implementation of a wit-imported interface on the interpreter and JVM backends (inert on WASM, where the host provides it) |
rontolisp:fetch starts an outgoing HTTP request and returns a future, resolved with
rontolisp:await; see the
HTTP Requests guide for a worked overview, and the
fetch,
await and
futurep reference pages for options, the
result plist, backend support, and limitations. rontolisp:http-handler is
the incoming counterpart of fetch -- it serves HTTP requests with a handler
function over the Clack environment plist and (status headers body)
response list; see the
Serving HTTP guide for a worked example on every
backend, and the http-handler reference
page for backend support and limitations. rontolisp:json-parse and
rontolisp:json-stringify convert between JSON documents and Lisp values
(a lightweight, com.inuoe.jzon-compatible subset) -- for example to parse a
fetch response body; see the
json-parse and
json-stringify reference pages for
the value mapping and limitations. rontolisp:json-span
and rontolisp:json-value read and edit a large
document without making Lisp values of all of it: byte offsets to splice at, or one
value. The tcp functions
(rontolisp:tcp-connect / tcp-listen / tcp-accept / tcp-local-port and
the address accessors)
open plain TCP sockets whose handles work with the standard stream functions
(read-line / write-line / read-byte / write-byte / close); see the
TCP Sockets guide for a worked echo server, and
the tcp-connect,
tcp-listen,
tcp-accept and
tcp-local-port reference pages for
backend support and limitations. A
usocket-compatible shim is layered over them for
portability with existing Common Lisp code. The TLS variants (rontolisp:tls-connect /
tls-upgrade / tls-listen / tls-listen-pem) wrap the same stream handles in TLS; see the
tls-connect,
tls-upgrade,
tls-listen and
tls-listen-pem reference pages.
rontolisp:wasm-export,
rontolisp:jvm-export,
rontolisp:wasm-import, rontolisp:wit-export and rontolisp:wit-import are
compile-time directives; jvm-export is wasm-export's JVM twin — a typed,
Java-callable entry point on a compiled class
(jvm-export); the WIT pair take a .wit file as the single source of
truth for a boundary, so the types are never hand-written. wit-export declares
that the program implements a WIT world (and --scaffold-wit generates the
implementation's skeleton from it); wit-import declares that it calls a WIT
interface, binding every function the interface declares as an ordinary Lisp
function — dispatched on the interpreter and JVM backends to a provider
(rontolisp:wit-provide), and lowered to
rontolisp:wasm-import on Preview 1 WASM, where the host is the provider, so one
source runs on every backend. rontolisp ships no provider for any interface:
it knows the provider mechanism, not what any particular interface is, so an
implementation of a WIT interface is ordinary Lisp code. A WIT result's error
arm signals the rontolisp:wit-error condition, whose payload is read with
rontolisp:wit-error-payload. See their
wasm-export,
wasm-import,
wit-export,
wit-import and
wit-provide reference pages and the
Compiling to WebAssembly guide.
rontolisp:interactive-interrupt is the condition Ctrl-C (SIGINT) is signalled as
on the interpreter and in a compiled JVM program, a serious-condition and not an
error, like SBCL's sb-sys:interactive-interrupt:
The signal starts once a handler-case or handler-bind clause names this
condition; a program with none, or one that only handles serious-condition, ends
at SIGINT with status 130. It arrives at the next function call or loop step of the
thread that established the first such handler, and it wakes sleep and
condition-wait. A call that does not wake, such as read-line on standard input,
leaves it pending, and a second SIGINT then ends the process. If every handler
declines, the process ends with status 130 without running unwind-protect
cleanups. In a WebAssembly program SIGINT always ends the process and no handler
runs, and the same goes for a JVM class a host calls or deploys (rontolisp:jvm-export,
--no-main, a .war), whose SIGINT belongs to the host.