spsc_ring.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
 A mutable single producer, single consumer ring of fixed size elements.
 
 One side pushes, the other pops, with no lock between them. The producer owns
 `tail` and the consumer owns `head`; both are monotonic counters, so the live
 slot for an index is `index & mask` and the capacity is a power of two. The
 acquire/release pairing makes it correct on weakly ordered processors, not only
 x86. A push releases the written element through `tail`, which the consumer
 reads with acquire; a pop releases the freed slot through `head`, which the
 producer reads with acquire.
*/
 
#pragma once
 
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
 
#include "serene/rt/errors.h"
 
// IMPORTANT: This type should be UNSIGNED
#define SRN_SPSC_RING_CAP_TYPE uint32_t
 
typedef struct srn_context_t srn_context_t;
 
typedef struct srn_spsc_ring_t {
  ERROR_HEADER;
 
  /// Consumer index. Only the consumer advances it.
  _Atomic size_t head;
 
  /// Producer index. Only the producer advances it.
  _Atomic size_t tail;
 
  SRN_SPSC_RING_CAP_TYPE cap;
  SRN_SPSC_RING_CAP_TYPE mask;
  size_t elem_size;
 
  /// `cap * elem_size` bytes. Typically owned by who ever owns
  /// the ring itself.
  unsigned char *buf;
} srn_spsc_ring_t;
 
/**
 * Set up a ring by allocating the `buf` to be the size of `cap * elem_size`.
 * And it will choose the `cap` to be `2 ^ magnitude`.
 */
srn_spsc_ring_t *srn_spsc_ring_make(srn_context_t *ctx, size_t magnitude, size_t elem_size);
 
/**
 * Producer side. Copy `*elem` into the ring. Returns false when the ring is
 * full, leaving it unchanged.
 */
bool srn_spsc_ring_push(srn_spsc_ring_t *r, const void *elem);
 
/**
 * Consumer side. Copy one element into `*out`. Returns false when the ring is
 * empty, leaving `*out` untouched.
 */
bool srn_spsc_ring_pop(srn_spsc_ring_t *r, void *out);
 
/**
 * Whether the ring currently holds no elements. For the consumer this is
 * exact; for any other observer it is a hint.
 */
bool srn_spsc_ring_empty(const srn_spsc_ring_t *r);