(rontolisp) docs
← Functions

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.

FunctionExampleResult
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.