event_ctx.h File Reference

#include <keel/allocator.h>
#include <keel/error.h>
#include <keel/event.h>
#include <stdint.h>

Include dependency graph for event_ctx.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	KlWatcher
	A registered FD watcher (heap-allocated, ctx-owned list). More...
struct	KlEventCtx
	Composable event loop context. More...

Typedefs
typedef void(*	KlWatcherFn) (int fd, KlEventMask ready, void *user_data)
	Callback invoked when a watched FD becomes ready.
typedef struct KlWatcher	KlWatcher
	A registered FD watcher (heap-allocated, ctx-owned list).
typedef struct KlTimerEntry	KlTimerEntry
	Timer heap entry (defined in src/timer.c).
typedef struct KlEventCtx	KlEventCtx
	Composable event loop context.

Functions
int	kl_event_ctx_init (KlEventCtx *ctx, KlAllocator *alloc)
	Initialize an event context with the given allocator.
void	kl_event_ctx_free (KlEventCtx *ctx)
	Free all watchers and close the event loop.
int	kl_watcher_add (KlEventCtx *ctx, int fd, KlEventMask mask, KlWatcherFn on_ready, void *user_data)
	Register a file descriptor with the event loop.
int	kl_watcher_mod (KlEventCtx *ctx, int fd, KlEventMask mask)
	Change the event interest mask for a registered watcher.
void	kl_watcher_del (KlEventCtx *ctx, int fd)
	Remove a watcher and deregister its FD from the event loop.
int	kl_watcher_rearm (KlEventCtx *ctx, int fd)
	Re-arm a watcher after its callback fires.
static int	kl_event_dispatch (KlEventCtx *ctx, const KlEvent *event)
	Dispatch a single event if it is a watcher (tagged pointer).
int	kl_event_ctx_run (KlEventCtx *ctx, int max_events, int timeout_ms)
	Run one tick of the event loop, dispatching all watcher events.

Typedef Documentation

KlWatcherFn

typedef void(* KlWatcherFn) (int fd, KlEventMask ready, void *user_data)

Callback invoked when a watched FD becomes ready.

Parameters

fd	File descriptor that fired.
ready	Bitmask of ready events (KL_EVENT_READ, KL_EVENT_WRITE).
user_data	Opaque pointer passed to kl_watcher_add.

KlWatcher

typedef struct KlWatcher KlWatcher

A registered FD watcher (heap-allocated, ctx-owned list).

KlTimerEntry

typedef struct KlTimerEntry KlTimerEntry

Timer heap entry (defined in src/timer.c).

KlEventCtx

typedef struct KlEventCtx KlEventCtx

Composable event loop context.

Contains the platform event loop, allocator, and watcher list. Embedded in KlServer via composition. Can also be used standalone (e.g. by KlClient, KlThreadPool) without requiring a full server.

Function Documentation

kl_event_ctx_init()

int kl_event_ctx_init	(	KlEventCtx *	ctx,
		KlAllocator *	alloc
	)

Initialize an event context with the given allocator.

Parameters

ctx	Event context to initialize.
alloc	Allocator (borrowed — must outlive ctx).

Returns

0 on success, -1 on failure.

kl_event_ctx_free()

void kl_event_ctx_free

(

KlEventCtx *

ctx

)

Free all watchers and close the event loop.

kl_watcher_add()

int kl_watcher_add	(	KlEventCtx *	ctx,
		int	fd,
		KlEventMask	mask,
		KlWatcherFn	on_ready,
		void *	user_data
	)

Register a file descriptor with the event loop.

When the FD becomes ready (readable/writable per mask), on_ready is called on the event loop thread. The watcher is heap-allocated and owned by the context — call kl_watcher_del to remove and free.

Returns

0 on success, -1 on failure.

kl_watcher_mod()

int kl_watcher_mod	(	KlEventCtx *	ctx,
		int	fd,
		KlEventMask	mask
	)

Change the event interest mask for a registered watcher.

Returns

0 on success, -1 if fd not found or event_mod fails.

kl_watcher_del()

void kl_watcher_del	(	KlEventCtx *	ctx,
		int	fd
	)

Remove a watcher and deregister its FD from the event loop.

kl_watcher_rearm()

int kl_watcher_rearm	(	KlEventCtx *	ctx,
		int	fd
	)

Re-arm a watcher after its callback fires.

Required for one-shot backends (io_uring POLL_ADD). Safe no-op if the watcher was removed during the callback. On persistent backends (epoll, kqueue) this is a harmless re-register.

kl_event_dispatch()

static int kl_event_dispatch ( KlEventCtx *  ctx, const KlEvent *  event  )

inlinestatic

Dispatch a single event if it is a watcher (tagged pointer).

Checks the LSB tag on event->udata. If set, unmasks the KlWatcher*, calls on_ready, re-arms for one-shot backends, and returns 1. If the tag is clear (connection, listen socket, etc.) returns 0 — the caller handles it.

Returns

1 if a watcher was dispatched, 0 otherwise.

kl_event_ctx_run()

int kl_event_ctx_run	(	KlEventCtx *	ctx,
		int	max_events,
		int	timeout_ms
	)

Run one tick of the event loop, dispatching all watcher events.

Calls kl_event_wait, then kl_event_dispatch for each returned event. Non-watcher events are silently skipped — this is intended for standalone KlEventCtx usage (clients, thread pools) where all FDs are watcher-owned.

Uses a stack buffer for up to 64 events; heap-allocates via ctx->alloc for larger requests.

Parameters

ctx	Event context (loop + allocator + watchers).
max_events	Maximum events to process per tick.
timeout_ms	Timeout in milliseconds (-1 for infinite).

Returns

Number of events returned by kl_event_wait, or -1 on error.