EXAMPLES

HIVEPARSER

The hiveparser.c application demonstrates a live telemetry dashboard built on Trafilo. It binds to a UDP socket, parses incoming structural logs, aggregates events per service, and renders a live terminal user interface via ncurses.

Application Architecture

The application separates data ingestion from visualization. Trafilo manages the high-throughput UDP stream and per-key temporal aggregation across multiple worker threads. A distinct background thread executes the ncurses render loop. A shared global structure, protected by a mutex, bridges the framework and the user interface.

/* Shared TUI State */
typedef struct {
    char            key[HP_KEY_MAX + 1];
    size_t          total_count;
    size_t          error_count;
    size_t          window_count;
    struct timespec last_seen;
    int             in_use;
} tui_row_t;

typedef struct {
    pthread_mutex_t lock;
    tui_row_t       rows[MAX_SERVICES];
    volatile int    shutdown;
} tui_state_t;

static tui_state_t g_tui;

Event Processing and State Isolation

The framework executes the parse_fn concurrently across the worker pool. The parser extracts the routing key from the raw buffer and allocates the event_t structure.

Trafilo acquires a bucket-specific lock before invoking handle_fn. The callback increments the event counter and executes a substring search across the payload to detect error signatures. The function executes without global locks.

static void handle_fn(const event_t *e, void *user_state) {
    service_state_t *s = (service_state_t *)user_state;
    s->total++;
    if (looks_like_error((const char *)e->payload, e->payload_len)) {
        s->errors++;
    }
}

State Synchronization

The framework invokes the sink_fn callback upon sliding window expiration. The worker thread acquires the global g_tui.lock, transfers the aggregated bucket state into the shared rendering structure, and releases the lock. This minimizes lock contention; workers synchronize globally only during the periodic emission phase, not during per-event ingestion.

static void sink_fn(const char *key, const window_result_t *result, void *user_state) {
    service_state_t *s = (service_state_t *)user_state;

    pthread_mutex_lock(&g_tui.lock);
    tui_row_t *row = tui_row_get(key);
    if (row) {
        row->total_count  = s->total;
        row->error_count  = s->errors;
        row->window_count = result->event_count;
        clock_gettime(CLOCK_MONOTONIC, &row->last_seen);
    }
    pthread_mutex_unlock(&g_tui.lock);
}

Build and Execute

Compile the examples target. Launch the parser. Start the dummy daemon container to transmit UDP traffic.

make examples
./build/examples/hiveparser &
cd dummyDameon && docker compose up

The parser process writes directly to standard output. Transmit a q character to terminate the process cleanly and restore terminal state.