libuv

Kind	ffi-zig
Capabilities	ffi net file
Categories	async networking ffi
Keywords	libuv async io event-loop networking

Asynchronous I/O library wrapping libuv for Kit

Files

File	Description
`.editorconfig`	Editor formatting configuration
`.gitignore`	Git ignore rules for build artifacts and dependencies
`.tool-versions`	asdf tool versions (Zig, Kit)
`LICENSE`	MIT license file
`README.md`	This file
`examples/timer-example.kit`	Repeating timer example
`kit.toml`	Package manifest with metadata, native linking, and tasks
`src/error.kit`	Libuv error type for typed error handling
`src/libuv.kit`	Public package entry point and consolidated API
`src/loop.kit`	Event loop API definitions
`src/timer.kit`	Timer API definitions
`tests/libuv.test.kit`	Tests for libuv error and handle types
`zig/callback_registry.zig`	Callback registry used to bridge libuv callbacks to Kit closures
`zig/kit_ffi.zig`	Kit FFI helper declarations used by the Zig bindings
`zig/libuv.zig`	Consolidated Zig FFI implementation linked against libuv
`zig/loop.zig`	Zig FFI implementation for event loop operations
`zig/timer.zig`	Zig FFI implementation for timer operations

Dependencies

No Kit package dependencies.

Native Requirements

This is an ffi-zig package and requires libuv headers and libraries at build time.

The package manifest links against uv and searches these include/library paths:

/opt/homebrew/include and /opt/homebrew/lib
/usr/local/include and /usr/local/lib
/usr/include and /usr/lib

On macOS with Homebrew:

brew install libuv

On Debian/Ubuntu:

sudo apt-get install libuv1-dev

Installation

kit add gitlab.com/kit-lang/packages/kit-libuv.git

Usage

import Concurrent.Atomic as Atomic

import Kit.Libuv as Libuv

main = fn =>
  println "Starting timer example..."

  # Get the default event loop
  loop = match Libuv.loop-default
    | Ok l -> l
    | Err e -> panic "Failed to get loop: ${e}"

  # Use an atomic counter because libuv invokes the callback from native code
  counter = Atomic.int-new 0

  # Start a repeating timer that fires every 500ms
  match Libuv.timer-start loop 500 500 (fn =>
    previous = Atomic.int-fetch-add counter 1 :seq-cst
    count = previous + 1
    println "Timer fired! Count: ${count}"

    if count >= 3 then
      Libuv.loop-stop loop
    else
      no-op
  )
    | Ok _ -> no-op
    | Err e -> panic "Timer failed: ${e}"

  # Run until the timer callback stops the loop
  match Libuv.loop-run loop :default
    | Ok _ -> println "Event loop finished."
    | Err e -> println "Loop error: ${e}"

main

API Overview

Event Loops

Function	Description
`loop-create`	Create a new independent event loop
`loop-default`	Get the default event loop
`loop-run`	Run the event loop with `:default`, `:once`, or `:nowait`
`loop-stop`	Stop the event loop
`loop-close`	Close an event loop after its handles have been closed
`loop-alive?`	Check whether a loop has active handles or requests
`loop-now`	Get the loop timestamp in milliseconds
`loop-update-time`	Update the loop's cached time

Timers

Function	Description
`timer-start`	Start a one-shot or repeating timer
`timer-stop`	Stop a timer
`timer-again`	Restart a repeating timer
`timer-set-repeat`	Set a timer repeat interval in milliseconds
`timer-get-repeat`	Get a timer repeat interval in milliseconds
`timer-get-due-in`	Get milliseconds until the timer fires
`timer-close`	Close a timer handle and free its resources

Errors and Handles

Fallible operations return Result T LibuvError.

Current handle types:

export type Loop = Loop {handle: Int}
export type Timer = Timer {handle: Int, loop-id: Int}

Development

Running Examples

Run examples with the interpreter:

kit run examples/timer-example.kit

Compile examples to a native binary:

kit build examples/timer-example.kit && ./timer-example

Running Tests

Run the test suite:

kit test

Run the test suite with coverage:

kit test --coverage

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

Format and check source files in src/
Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html.

Cleaning Build Artifacts

Remove generated files, caches, native artifacts, and coverage output:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/libuv/, making it available for import as Kit.Libuv in other projects.

Implementation Notes

libuv uses C function pointer callbacks. This package bridges those callbacks to Kit closures with a handle ID system, a Zig callback registry, and C-callable trampoline functions.

License

This package is released under the MIT License - see LICENSE for details.

libuv is also released under the MIT License.

Exported Functions & Types

`LibuvError`

Libuv error type for typed error handling. All libuv operations that can fail return Result T LibuvError.

Variants

LibuvError {message}

`Loop`

Event loop handle

Variants

Loop {handle}

`Timer`

Timer handle

Variants

Timer {handle, loop-id}

`LibuvError`

Libuv error type for typed error handling. All libuv operations that can fail return Result T LibuvError.

Variants

LibuvError {message}

`Timer`

Timer handle

Variants

Timer {handle, loop-id}

`Loop`

Event loop handle

Variants

Loop {handle}