[[https://github.com/Kiyomi-Computation-Systems/chez-libuv/actions/workflows/ci.yml][https://github.com/Kiyomi-Computation-Systems/chez-libuv/actions/workflows/ci.yml/badge.svg]]
R6RS bindings to [[https://libuv.org][libuv]] for Chez Scheme: an event loop, TCP, timers,
DNS, child processes, pipes and signals.
#+begin_quote
✨ AI Disclosure: LLMs are used extensively in the planning and development of this project.
#+end_quote
⚠ This is not a web server.
You can use this to /build/ a server like [[https://github.com/Kiyomi-Computation-Systems/chez-http-server][chez-http-server]], or anything that needs async I/O using
libuv.
It is a thin, legible mirror of libuv. The API follows libuv's own verbs
(accept, read-start, write, shutdown, timer, getaddrinfo,
spawn, close) closely.
It is transport only. It parses nothing, only understands raw bytes, and
has no connection-state or backpressure policy of its own. Those belong
to layers built on top of it.
- Closing is explicit. A handle stays open until you close it, and
callbacks run only inside
uv-run. No guardian or finalizer tears down
native state behind your back, so a handle's lifetime is visible in
your code.
- Bytes are copied at the boundary. Every read delivers a fresh
bytevector, and every write copies its bytes before libuv sees them. No
Scheme object is shared with C while libuv holds it.
- Errors have names. libuv's error codes arrive as symbols
(
'ECONNREFUSED) inside R6RS conditions, and every refusal the binding
makes is named by condition type (&uv-handle-closed) or by a
reason symbol ('loop-running).
- A blocked loop does not stall the collector. A thread waiting in
uv-run lets other Scheme threads collect garbage. Each loop belongs to
one thread at a time, the one that created it or last ran it. Every
verb that makes something on it, and every verb on its open handles
except uv-close! and uv-async-send!, raises &uv-wrong-thread from
any other thread. uv-async-send! is how another thread wakes it.
- Native calls are checked. A verb on a closed handle or loop raises
&uv-handle-closed instead of touching freed memory, even when an
engine stops it part way; closing one twice does nothing. A run raises
&uv-stack-exhausted instead of starting when its thread has less than
128 KiB of C stack left.
| Module | Binds |
|-------------------+------------------------------------------------------------------|
| (libuv) | Everything below, the condition types and the version queries |
| (libuv loop) | Loops: run, stop, the cached clock, close and teardown |
| (libuv handle) | What every handle shares, and TCP and pipe socket buffer sizes |
| (libuv timer) | One-shot and repeating timers |
| (libuv tcp) | Bind, listen, accept, connect, nodelay, keepalive, addresses |
| (libuv stream) | Reads with backpressure, scalar and vectored writes, shutdown |
| (libuv pipe) | Pipes for child-process stdio |
| (libuv process) | Child processes with libuv's full stdio vocabulary, and kill |
| (libuv signal) | Signal watching, continuous or one-shot |
| (libuv async) | Waking a loop from another thread |
| (libuv dns) | getaddrinfo, getnameinfo and cancellation |
There is no filesystem API, no UDP and no zero-copy I/O. Linux and macOS
are supported; Windows is not.
- Chez Scheme 10.4.1 or later, threaded. That is Chez's default build:
anything not configured with
--nothreads. A non-threaded Chez is
refused at import, with a message saying so.
- libuv 1.48.0 or later in the 1.x series, as a system package
pkg-config can see (brew install libuv, Ubuntu 24.04's
libuv1-dev). Without one, or when the system's libuv is older than
1.48.0, the build uses the pinned libuv in vendor/libuv.
- A C compiler and
make. Building the vendored libuv also needs cmake.
#+begin_src sh
git clone --recursive https://github.com/Kiyomi-Computation-Systems/chez-libuv.git
cd chez-libuv
make build
#+end_src
make build compiles the small C shim and generates
src/libuv/private/config.sls, which records absolute paths for /this/
machine. That file is not in the repository, so every clone runs
make build once before (import (libuv)) resolves. Run it again after
every upgrade: a shim built from older sources fails the import with
&uv-shim-unavailable. make help lists every target, and
[[file:docs/building.md][docs/building.md]] covers acquisition paths,
CHEZ_LIBUV_SHIM and release builds.
The shim and config.sls are per-machine build products, so a copy of
the sources alone cannot load. A project that depends on chez-libuv
through Akku gets them from its install hook, scripts/akku-install,
which akku install runs before it installs the libraries: it builds a
release shim into the project's .akku/ffi against the libuv pkg-config
finds, and writes config.sls naming it.
[[file:docs/installing.md#akku][docs/installing.md]] has the lines a
project's Akku.manifest needs to run it, and what each failure says. Akku
also manages the test suites' Scheme dependency (chez-srfi); (libuv)
itself depends on nothing beyond (rnrs).
Chez needs src on its library path:
#+begin_src sh
CHEZSCHEMELIBDIRS=src chez --program your-script.sps
#+end_src
make dev starts a REPL with everything wired.
#+begin_src scheme
(import (rnrs) (libuv))
(define loop (make-uv-loop))
(define timer (make-uv-timer loop))
(define fires 0)
(uv-timer-start! timer
(lambda (t) ; the callback receives the timer
(set! fires (+ fires 1))
(display "tick\n")
(when (= fires 3)
(uv-timer-stop! t)
(uv-close! t)))
0 100) ; first fire now, then every 100 ms
(uv-run loop 'default) ; callbacks run here and nowhere else
(uv-loop-teardown! loop)
#+end_src
[[file:docs/quickstart.md][docs/quickstart.md]] walks through an echo
server and client on one loop, and the three rules every program here
depends on.
make test runs the default suites; the root-only and threading-stress
suites have targets of their own (make help). On Linux,
make HAVE_PKG=no test-memory runs the suites under Valgrind, which is
the memory gate; on macOS the same target uses AddressSanitizer, which
checks addresses but not leaks. On a Guix host, scripts/guix-env make test
runs them in a pinned container. CI runs on Linux; macOS is tested locally.
[[file:docs/building.md][docs/building.md]] describes each gate, and
[[file:CONTRIBUTING.md][CONTRIBUTING.md]] the test discipline.
The guides start at [[file:docs/README.md][docs/README.md]]. make site
renders them into build/site/, the pages published on GitHub Pages.
| [[file:docs/installing.md][Installing]] | What you need, building the shim, importing (libuv) |
| [[file:docs/quickstart.md][Quickstart]] | An echo server start to finish, and the rules that make it work |
| [[file:docs/loops.md][The event loop]] | Making, running, stopping and tearing down a loop |
| [[file:docs/callbacks.md][Callbacks]] | What a callback may do, raises, escapes and engines |
| [[file:docs/threads.md][Threads]] | One thread per loop, handing a loop over, async wakeups |
| [[file:docs/timers.md][Timers]] | One-shot and repeating timers |
| [[file:docs/tcp.md][TCP and streams]] | Listening, connecting, reading and writing |
| [[file:docs/flow-control.md][Flow control]] | Buffers, the write queue, pausing reads |
| [[file:docs/processes.md][Processes and pipes]] | Running a child and talking to it |
| [[file:docs/signals.md][Signals]] | Catching signals on the loop |
| [[file:docs/dns.md][DNS]] | Names to addresses and back |
| [[file:docs/errors.md][Errors]] | Every condition the library raises |
| [[file:docs/reference.md][API reference]] | Every exported binding, checked against the source |
| [[file:docs/building.md][Building and testing]] | Acquisition paths, release builds, test gates, the docs site |
| [[file:CHANGELOG.md][CHANGELOG]] | Per-release history |
See [[file:CONTRIBUTING.md][CONTRIBUTING.md]] for the build and test
workflow, and [[file:SECURITY.md][SECURITY.md]] for reporting
vulnerabilities privately.
BSD 3-Clause; see [[file:LICENSE][LICENSE]]. Third-party components and
their licenses are listed in [[file:NOTICE][NOTICE]].
© [[https://kiyomicomputation.systems/][Kiyomi Computation Systems LLC]], all rights reserved.
