xtc_io.h

/*-
 * Copyright (c) 2026, The XTC Project
 * Use of this source code is governed by the ISC License.
 *
 * src/inc/xtc_io.h
 *      The L1 event-notification engine: register interest in fd
 *      readiness, poll for ready events, wake the poller from another
 *      thread.
 *
 *      Exactly one backend is compiled in per binary (configure-time).
 *      M2 ships poll(2) and epoll; later milestones add io_uring,
 *      kqueue, IOCP, Solaris event ports, and AIX pollset.
 *
 *      See M2_CLAIMS.md.
 */
 
#ifndef XTC_IO_H
#define XTC_IO_H
 
#include <stdint.h>
 
typedef struct xtc_io xtc_io_t;
 
/*
 * Event flag bits.  Stable across minor versions; new flags appear
 * at higher bit positions only (PLAN.md (S)18).
 */
#define XTC_IO_READABLE  0x01u
#define XTC_IO_WRITABLE  0x02u
#define XTC_IO_HUP       0x04u
#define XTC_IO_ERR       0x08u
#define XTC_IO_WAKEUP    0x10u   /* set on the synthetic event delivered
                                    by xtc_io_wakeup; tag is NULL. */
#define XTC_IO_AIO       0x20u   /* set on an async file-I/O completion;
                                    tag is the xtc_aio_t's tag. */
 
typedef struct xtc_io_event {
        void     *tag;        /* the value passed at registration; NULL on wakeups */
        uint32_t  flags;      /* XTC_IO_* bitset */
} xtc_io_event_t;
 
/*
 * Async file I/O.  A native completion-based file operation: io_uring
 * submits IORING_OP_READ/WRITE/FSYNC; kqueue submits POSIX AIO with
 * SIGEV_KEVENT and reaps EVFILT_AIO; IOCP uses overlapped reads/writes
 * on the port -- in each case the completion wakes the tagged task.  On
 * a readiness-only backend (epoll, poll, select, event ports, AIX)
 * xtc_io_aio_submit returns XTC_E_NOSYS and the caller offloads the op
 * to the blocking pool instead, because a regular file is not pollable.
 * See xtc_aio(3).
 */
enum {
        XTC_AIO_PREAD     = 0,
        XTC_AIO_PWRITE    = 1,
        XTC_AIO_FSYNC     = 2,    /* full sync: data + metadata */
        XTC_AIO_FDATASYNC = 3,    /* data only (fsync on macOS, which lacks it) */
        XTC_AIO_PREADV    = 4,    /* vectored read (iov/iovcnt) */
        XTC_AIO_PWRITEV   = 5     /* vectored write (iov/iovcnt) */
};
typedef struct xtc_aio {
        int       fd;
        int       op;         /* XTC_AIO_* */
        void     *buf;        /* read/write buffer (scalar ops; NULL for FSYNC/V) */
        uint32_t  len;        /* byte count (scalar ops) */
        int64_t   off;        /* file offset (ignored for FSYNC) */
        void     *tag;        /* woken on completion (an xtc_task_t *) */
        int       done;       /* 0 until the completion is reaped */
        int32_t   res;        /* bytes transferred, or -errno */
        /* Vectored ops (PREADV / PWRITEV): iov points at the caller's
         * iovec array (struct iovec *, kept opaque here to avoid a
         * <sys/uio.h> dependency in this header) and iovcnt is its count.
         * Zero/NULL for the scalar and sync ops. */
        void     *iov;        /* const struct iovec * */
        int       iovcnt;
} xtc_aio_t;
 
/*
 * PUBLIC: int          xtc_io_init __P((xtc_io_t **));
 * PUBLIC: int          xtc_io_fini __P((xtc_io_t *));
 * PUBLIC: const char  *xtc_io_backend_name __P((void));
 * PUBLIC: int          xtc_io_reg_fd __P((xtc_io_t *, int, uint32_t, void *));
 * PUBLIC: int          xtc_io_mod_fd __P((xtc_io_t *, int, uint32_t, void *));
 * PUBLIC: int          xtc_io_del_fd __P((xtc_io_t *, int));
 * PUBLIC: int          xtc_io_poll __P((xtc_io_t *, xtc_io_event_t *, int, int64_t, int *));
 * PUBLIC: int          xtc_io_aio_submit __P((xtc_io_t *, xtc_aio_t *));
 * PUBLIC: int          xtc_io_wakeup __P((xtc_io_t *));
 */
 
/* Lifecycle. */
int          xtc_io_init(xtc_io_t **out);
int          xtc_io_fini(xtc_io_t *io);
const char  *xtc_io_backend_name(void);
 
/* Registration. */
int          xtc_io_reg_fd(xtc_io_t *io, int fd, uint32_t interest, void *tag);
int          xtc_io_mod_fd(xtc_io_t *io, int fd, uint32_t interest, void *tag);
int          xtc_io_del_fd(xtc_io_t *io, int fd);
 
/*
 * xtc_io_poll --
 *      Wait for events.  On return *n_out holds the number of events
 *      written (0..max).
 *
 *      timeout_ns:
 *              == 0  -> non-blocking
 *              >  0  -> wait at most that many nanoseconds
 *              <  0  -> wait indefinitely (until an fd becomes ready or
 *                       xtc_io_wakeup is called)
 */
int          xtc_io_poll(xtc_io_t *io, xtc_io_event_t *events, int max,
                         int64_t timeout_ns, int *n_out);
 
/* Submit an async file op.  XTC_OK if queued (the caller parks until
 * the completion event with tag a->tag arrives, then reads a->res);
 * XTC_E_NOSYS if the backend has no native file completion (caller
 * should offload instead). */
int          xtc_io_aio_submit(xtc_io_t *io, xtc_aio_t *a);
 
/*
 * xtc_io_wakeup --
 *      From any thread, cause the next (or in-flight) xtc_io_poll on
 *      this io to return.  Safe to call concurrently from many threads;
 *      multiple wakeups before the next poll coalesce into one event.
 */
int          xtc_io_wakeup(xtc_io_t *io);
 
#endif /* XTC_IO_H */