A single-header C library for TCP and Unix-socket messaging on Linux.

A background thread runs epoll; your thread polls a lock-free queue. Messages are length-prefixed; broadcasts are refcounted instead of copied. ~1600 LOC, no dependencies beyond libc and pthreads. Apache 2.0.

Contents

• Quickstart
• How it works
• Wire protocol
• API reference
• Examples
• Threading rules
• Configuration
• Limits and non-goals
• License

Quickstart

#define VIBE_IMPLEMENTATION
#include "vibe.h"

Define VIBE_IMPLEMENTATION in exactly one translation unit, or compile with -DVIBE_IMPLEMENTATION. Compile with -pthread, GCC or Clang, on Linux.

make             # builds examples/{chat_server,ping_client,firehose,telemetry_sink}

Minimal echo server:

#define VIBE_IMPLEMENTATION
#include "vibe.h"
#include <unistd.h>

int main(void) {
    vibe_hub_t* hub = vibe_hub_start();
    vibe_listen(hub, "0.0.0.0:8080");

    for (;;) {
        vibe_msg_t* batch = vibe_poll(hub);
        if (!batch) { usleep(100); continue; }

        vibe_for_each(msg, batch) {
            if (msg->type == VIBE_EVENT_DATA)
                vibe_send_msg(msg->conn, msg->data, msg->len);
        }
        vibe_free(batch);
    }
}

How it works

• Hub owns the epoll fd, an eventfd for cross-thread wakeups, and one IO thread.
• IO thread runs epoll_wait (edge-triggered, EPOLLIN | EPOLLOUT | EPOLLET | EPOLLRDHUP). It accepts, reads, frames, and writes. New events go into the inbox.
• Inbox is an MPSC injector queue with a CAS'd "consuming" bit — multiple application threads MAY call vibe_poll; one wins and drains, the others get NULL.
• Outbox lives per connection — also an MPSC queue. Any thread can call vibe_send_msg. The IO thread is woken via the eventfd and drains writes.
• Dirty queue signals which connections have pending writes since the last epoll cycle.
• Broadcast allocates the payload once, hands a refcounted vibe_chunk_t* to each recipient's outbox, and frees on last release.
• Backpressure is per-connection: pending_bytes is an atomic counter; once it crosses VIBE_MAX_PENDING_BYTES (default 2 GiB), vibe_send_msg returns false.

There is no internal blocking call you wait on. vibe_poll is wait-free. If there's nothing to do, it returns NULL — sleep, spin, or epoll your own fds, your call.

Wire protocol

Every message is framed as:

+--------+----------+
|  u32   | payload  |
| length | (N bytes)|
+--------+----------+

• 4-byte big-endian length prefix.
• Hard cap on incoming frames: 10 MiB. Larger frames cause the connection to be dropped.
• Outgoing frames are limited only by VIBE_MAX_PENDING_BYTES and the uint32_t length field (4 GiB - 1).
• Receiver delivers whole frames or nothing. Partial frames sit in the per-connection 8 KiB read buffer until complete.

Both peers must speak this framing. If you need HTTP, WebSocket, or anything else, layer it on top.

API reference

Types

typedef struct vibe_net_ctx   vibe_hub_t;   // opaque hub
typedef struct vibe_connection vibe_conn_t; // opaque connection (peer or listener)

typedef struct vibe_msg {
    struct vibe_msg* next;  // linked-list of events in this batch
    int              type;  // VIBE_EVENT_DATA | _CONNECTED | _DISCONNECTED
    vibe_conn_t*     conn;  // source/peer connection
    uint32_t         len;   // payload length (0 for non-DATA events)
    char*            data;  // payload pointer (valid until vibe_free(batch))
} vibe_msg_t;

enum {
    VIBE_EVENT_DATA = 0,
    VIBE_EVENT_CONNECTED,
    VIBE_EVENT_DISCONNECTED,
};

Lifecycle

vibe_hub_t* vibe_hub_start(void);
void        vibe_hub_stop(vibe_hub_t* hub);

vibe_hub_start creates the epoll fd + eventfd and spawns the IO thread. Returns NULL on resource exhaustion.

vibe_hub_stop flips the running flag, kicks the eventfd, joins the IO thread, closes both fds, and frees the hub. Drain the inbox first if you care about not leaking the last batch.

Wiring

bool vibe_listen(vibe_hub_t* hub, const char* addr);
void vibe_dial  (vibe_hub_t* hub, const char* addr);
void vibe_close_conn(vibe_conn_t* conn);

Address grammar:

The format is detected from the first byte: digit or : → TCP, otherwise Unix.

vibe_listen returns false if socket, bind, or listen fails. Listener backlog is 512. SO_REUSEADDR is set. For TCP peers, TCP_NODELAY is also set on accepted sockets.

vibe_dial is non-blocking. Success/failure of the connect arrives later as a VIBE_EVENT_CONNECTED event (failure is currently silent — the socket is closed and no event fires; check with a timeout).

vibe_close_conn shuts the socket and releases the connection's reference. The IO thread will deliver a DISCONNECTED event shortly after.

Receiving

vibe_msg_t* vibe_poll(vibe_hub_t* hub);
void        vibe_free(vibe_msg_t* batch);

vibe_poll returns a linked-list batch of up to 256 events, or NULL if the inbox is empty (or another thread is currently draining). It does not block. Iterate with vibe_for_each(msg, batch) { ... }. msg->data and msg->conn are valid until you call vibe_free; copy them out if you need to hold on.

vibe_free releases the whole batch back to an internal pool and decrements each conn's refcount.

Sending

bool vibe_send_msg (vibe_conn_t*  conn,  const void* data, uint32_t len);
bool vibe_multicast(vibe_conn_t** conns, int count, const void* data, uint32_t len);

Both copy data once into a refcounted chunk. The chunk is dropped only after every recipient finishes writing. The data buffer you passed is yours again as soon as the call returns.

vibe_send_msg returns false if that one connection is over VIBE_MAX_PENDING_BYTES. Try again later or hang up.

vibe_multicast skips recipients over the limit and queues to the rest. Returns true if at least one recipient accepted, false if all were full (in which case the chunk is freed). There is no per-recipient status — if you need that, loop over vibe_send_msg.

Iteration macro

#define vibe_for_each(msg, batch) \
    for (vibe_msg_t* msg = (batch); msg != NULL; msg = msg->next)

Low-level aliases

The "ergonomic" names above are inline wrappers around shorter primitives that share the same ABI. Either set works:

Examples

All examples live in examples/. Build with make.

chat_server — accept and broadcast

Tracks connected peers, fans out every received message to all of them via refcounted multicast.

vibe_hub_t* hub = vibe_hub_start();
vibe_listen(hub, "0.0.0.0:8080");

vibe_conn_t* users[1024];
int n = 0;

while (running) {
    vibe_msg_t* batch = vibe_poll(hub);
    if (!batch) { usleep(500); continue; }

    vibe_for_each(msg, batch) {
        switch (msg->type) {
        case VIBE_EVENT_CONNECTED:
            if (n < 1024) users[n++] = msg->conn;
            break;
        case VIBE_EVENT_DATA:
            vibe_multicast(users, n, msg->data, msg->len);
            break;
        case VIBE_EVENT_DISCONNECTED:
            // remove from users[]
            break;
        }
    }
    vibe_free(batch);
}

Run: ./examples/chat_server 8080. Connect with any framed-TCP client.

ping_client — request/response RTT

Dials a peer, waits for CONNECTED, then sends "PING" five times and measures wall-clock RTT to the response. Demonstrates the connect-then-wait handshake pattern.

vibe_dial(hub, "127.0.0.1:8080");

vibe_conn_t* server = NULL;
while (!server) {
    vibe_msg_t* batch = vibe_poll(hub);
    if (batch) {
        vibe_for_each(msg, batch)
            if (msg->type == VIBE_EVENT_CONNECTED) server = msg->conn;
        vibe_free(batch);
    }
}

for (int i = 0; i < 5; i++) {
    uint64_t t0 = nanos();
    vibe_send_msg(server, "PING", 4);

    for (bool got = false; !got; ) {
        vibe_msg_t* batch = vibe_poll(hub);
        if (!batch) continue;
        vibe_for_each(msg, batch)
            if (msg->type == VIBE_EVENT_DATA) got = true;
        vibe_free(batch);
    }
    printf("Seq %d: %.2f us\n", i, (nanos() - t0) / 1000.0);
}

Run: ./examples/ping_client 8080 (against a server that echoes).

firehose — backpressure

Floods a peer with 1 KiB messages, backing off whenever vibe_send_msg returns false instead of growing the outbox unbounded.

char junk[1024];
while (1) {
    if (vibe_send_msg(conn, junk, sizeof junk)) {
        total_sent++;
    } else {
        usleep(100);  // backpressure — let the IO thread drain
    }
    vibe_msg_t* b = vibe_poll(hub);
    if (b) vibe_free(b);  // drain CONNECTED/DISCONNECTED so they don't pile up
}

The lesson: ignoring the return value of vibe_send_msg is how you OOM. Once pending_bytes > VIBE_MAX_PENDING_BYTES, sends drop on the floor — handle the false case.

telemetry_sink — many-to-one ingest

Accepts connections, counts messages and bytes, prints rates once a second.

vibe_listen(hub, "0.0.0.0:9090");
uint64_t msgs = 0, bytes = 0;
time_t last = time(NULL);

while (1) {
    vibe_msg_t* batch = vibe_poll(hub);
    if (batch) {
        vibe_for_each(msg, batch)
            if (msg->type == VIBE_EVENT_DATA) { msgs++; bytes += msg->len; }
        vibe_free(batch);
    } else { usleep(10); }

    time_t now = time(NULL);
    if (now > last) {
        printf("%lu msgs/s | %.2f MB/s\n", msgs, bytes / (1024.0*1024));
        msgs = bytes = 0; last = now;
    }
}

Threading rules

After vibe_free, do not touch any msg->data or msg->conn from that batch — conn may have been the last reference and freed.

Configuration

These are #defines overridable before including vibe.h in the implementation TU:

Compile-time constants (not user-overridable, change in source if you must):

Sockets are configured with SO_REUSEADDR, O_NONBLOCK, and (for TCP) TCP_NODELAY. Epoll registrations use EPOLLIN | EPOLLOUT | EPOLLET | EPOLLRDHUP for peers and EPOLLIN for listeners.

Limits and non-goals

• Linux only. Uses epoll, eventfd, accept4, and abstract Unix sockets. No macOS, Windows, or BSD.
• No TLS. Run behind a terminator (stunnel, nginx, envoy) if you need it.
• No UDP. TCP and Unix stream sockets only.
• No protocol above the framing. No HTTP, WebSocket, gRPC. Bring your own.
• Incoming frames > 10 MiB drop the connection. Increase the constant in source if you need bigger frames; this is a DoS guard.
• No graceful shutdown drain. vibe_hub_stop does not flush the inbox or pending outboxes — drain first if it matters.
• vibe_dial failures are silent. A failed connect closes the fd without firing an event; use a timeout.
• Single-consumer in practice. vibe_poll is multi-thread-safe but serialized; sharding across hubs scales further than fanning out consumers on one hub.

License

Apache 2.0. Copyright (c) 2026 Praveen Vaddadi thynktank@gmail.com. Contributing: see CONTRIBUTING.md.