internal.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/>.
 */
 
#pragma once
 
#include <stdatomic.h>
 
#include "serene/rt/context.h"
#include "serene/rt/fiber/thread.h"
#include "serene/rt/impl/pqmh.h"
#include "serene/rt/impl/spsc_ring.h"
#include "serene/rt/reactor.h"
 
/// A channel, the per-worker submission and completion ring pair.
typedef struct srn_reactor_io_channel_t {
  // requests: worker -> reactor
  srn_spsc_ring_t *sq;
  // completions: reactor -> worker
  srn_spsc_ring_t *cq;
  /// Operations submitted on this channel and not yet consumed. Touched only
  /// by the channel's owning worker os thread (the submit path bumps it, the
  /// consume path drops it), so it needs no atomics. Admission control caps
  /// it at the ring capacity, which is what makes a full SQ or CQ
  /// impossible.
  size_t inflight;
} srn_reactor_io_channel_t;
 
struct srn_reactor_t {
  srn_context_t *ctx;
 
  /// The chosen kernel mechanism and its private state, set at activation.
  const srn_reactor_backend_t *backend;
  void *backend_state;
 
  /// Wakes the worker that owns a channel a completion landed on. Set at
  /// activation.
  srn_reactor_notify_fn notify;
 
  /// One channel per worker, there is a 1to1 mapping between worker ids and
  /// channel ids. Basically their index in their respective array should match
  srn_reactor_io_channel_t *channels;
  size_t nchannels;
 
  /// Capacity of every ring (1 << ring_magnitude), fixed at activation. Also
  /// each channel's in-flight cap; see srn_reactor_submit.
  size_t ring_capacity;
 
  /// The reactor thread and its run flag. The thread loops until `running` is
  /// cleared and it is roused.
  srn_thread_t thread;
  _Atomic bool running;
 
  /// Operations submitted but not yet consumed, across all channels.
  /// Quiescence needs this to reach zero. Bumped on submit, dropped by the
  /// consumer through srn_reactor_op_done once the waiting fiber is readied.
  _Atomic size_t inflight;
 
  /// Pending timers (like SLEEP, and IO deadlines) as a min-heap keyed by
  /// absolute monotonic deadline. Created at activation, owned and touched only
  /// by the reactor thread (THIS IS NOT THREAD SAFE, so only the reactor should
  /// manage it). See the timer helpers in reactor.c.
  pqmh_t timers;
};
 
/**
 * Post a finished operation to `channel`'s completion queue and rouse the
 * channel's worker through the notify mechanism. Runs on the reactor thread,
 * called by the core for ops it completes itself (such as NOP) and by a backend
 * when a descriptor operation finishes. It does NOT drop the in-flight count:
 * that is the consumer's job via `srn_reactor_op_done`, so an op counts as gone
 * only once the waiting fiber has been readied, never in the gap between.
 */
[[gnu::nonnull(1)]]
void srn_reactor_post_completion(
  srn_reactor_t *reactor, size_t channel, srn_reactor_io_completion_t completion
);
 
/**
 * Return the shared, immutable error for an IO failure `tag`. These live in
 * static storage, not a context, so a completion or result can point one at
 * `maybe_error` with no allocation and no lifetime concern, and it is safe to
 * share across threads. A backend maps its native code (via srn_errno_to_tag
 * on POSIX) to a tag, then to one of these. Any tag without a dedicated entry
 * yields the UNKNOWN_IO_ERROR error.
 */
srn_error_t *srn_reactor_errors_static(srn_error_tag_t tag);