backend.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
/** @file
 Internal reactor backend interface.
 
 A backend is a set of functions that realises the completion based reactor
 contract: epoll, or io_uring backends on Linux, kqueue or IOCP and so on. Each
 backend lives in its own platform specific file under `rt/reactor/backend/` and
 exposes a single vtable instance. The reactor core selects one at activation.
*/
 
#pragma once
 
#include <stdbool.h>
#include <stdint.h>
 
#include "serene/rt/errors.h"
#include "serene/rt/reactor.h"
 
/**
 * No declared capabilities.
 */
#define SRN_REACTOR_BACKEND_FEAT_NONE 0
 
/**
 * The backend cannot wait on regular file readiness, so the core serves
 * regular file READ and WRITE off the backend, a synchronous syscall on the
 * calling worker (a dedicated blocking thread pool is the planned
 * replacement). Readiness backends
 * (likes of epoll, kqueue) set this; completion backends (likes of io_uring,
 * IOCP) submit file IO natively and leave it clear.
 */
#define SRN_REACTOR_BACKEND_FEAT_FILE_OFFLOAD 1U
 
/**
 * One async system behind the reactor contract. The reactor core drives these
 * on the reactor thread.
 */
typedef struct srn_reactor_backend_t {
  /// A short name for diagnostics, for example "epoll".
  const char *name;
 
  /// Bitmap of SRN_REACTOR_BACKEND_FEAT_* flags this backend requires from the
  /// reactor.
  uint32_t features;
 
  /// Initialize the backend in the given `reactor`.
  srn_error_t *(*init)(srn_reactor_t *reactor);
 
  /// Clean up after the backend.
  void (*shutdown)(srn_reactor_t *reactor);
 
  /// Submit a new request to the backend. Failures are reported to the waiting
  /// fiber by posting a completion, not returned, so there is nothing to check.
  void (*submit)(srn_reactor_t *reactor, size_t channel, const srn_reactor_io_request_t *req);
 
  /// Wait for readiness and complete any ready operations. Errors here are
  /// either benign (EINTR) or setup bugs, so nothing is returned.
  void (*wait)(srn_reactor_t *reactor, int timeout_ms);
 
  void (*wake)(srn_reactor_t *reactor);
 
} srn_reactor_backend_t;
 
extern const srn_reactor_backend_t srn_reactor_backend_epoll;