spsc.h File Reference

Single-producer, single-consumer channel. More...

#include "claim.h"
#include "err.h"

Go to the source code of this file.

Macros
#define	make_spsc(N, T)
	Convenience macro for allocating a new spsc.
#define	sizeof_spsc(N, T)
	Convenience macro for calculating the size of a spsc with certain parameters.
#define	spsc_send1(C, SRC)
	Convenience macro for sending a single item to a channel.
#define	spsc_nbsend1(C, SRC)
	Convenience macro for sending a single item to a channel.
#define	spsc_recv1(C, DST)
	Convenience macro for receiving a single item from a channel.
#define	spsc_nbrecv1(C, DST)
	Convenience macro for receiving a single item from a channel.

Functions
size_t	spsc_open (void *c, size_t nel, size_t elsize)
	Constructs a spsc in-place, or calculates the needed allocation size for one.
struct spsc *	spsc_alloc (size_t nel, size_t elsize)
	Allocates a new spsc using malloc() and opens it.
enum chic_err	spsc_close (struct spsc *c)
	Closes a channel, forbidding any future send operations on it.
size_t	spsc_nel (struct spsc *c)
	Gets the maximim number of elements a channel is capable of holding at once.
enum chic_err	spsc_send_init (struct spsc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
enum chic_err	spsc_send_nbinit (struct spsc *c, size_t n, struct claim *s)
	Claims up to an amount of space in the channel to be manually written into.
void	spsc_send_fini (struct spsc *c, struct claim *s)
	Commits a claim, indicating the item slots within have been written to and are ready to be received.
enum chic_err	spsc_send (struct spsc *restrict c, size_t n, void *restrict src)
	Sends items to a channel.
enum chic_err	spsc_nbsend (struct spsc *restrict c, size_t n, size_t *restrict n2, void *restrict src)
	Sends whatever items will fit to a channel.
enum chic_err	spsc_sendv (struct spsc *restrict c, size_t n,...)
	Sends items to a channel.
enum chic_err	spsc_nbsendv (struct spsc *restrict c, size_t n, size_t *restrict n2,...)
	Sends whatever items will fit to a channel.
enum chic_err	spsc_recv_init (struct spsc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
enum chic_err	spsc_recv_nbinit (struct spsc *c, size_t n, struct claim *r)
	Claims up to an amount of space in the channel to be manually read from.
void	spsc_recv_fini (struct spsc *c, struct claim *r)
	Commits a claim, indicating the item slots within have been read from and are safe to be overwritten.
enum chic_err	spsc_recv (struct spsc *restrict c, size_t n, void *restrict dst)
	Receives items from a channel.
enum chic_err	spsc_nbrecv (struct spsc *restrict c, size_t n, size_t *restrict n2, void *restrict dst)
	Receives whatever items are available from a channel.
enum chic_err	spsc_recvv (struct spsc *restrict c, size_t n,...)
	Receives items from a channel.
enum chic_err	spsc_nbrecvv (struct spsc *restrict c, size_t n, size_t *restrict n2,...)
	Receives whatever items are available from a channel.

Detailed Description

Single-producer, single-consumer channel.

Author

Fawn rubie.nosp@m.fawn.nosp@m.@prot.nosp@m.on.m.nosp@m.e

Date

2026

Macro Definition Documentation

make_spsc

#define make_spsc	(		N,
			T )

Value:

spsc_alloc((N), sizeof(T))

Convenience macro for allocating a new spsc.

Parameters

N	The capacity of the channel; must be a nonzero power of 2
T	The type of a channel element

See also

spsc_alloc

sizeof_spsc

#define sizeof_spsc	(		N,
			T )

Value:

spsc_open(NULL, (N), sizeof(T))

Convenience macro for calculating the size of a spsc with certain parameters.

Parameters

N	The capacity of the channel; must be a nonzero power of 2
T	The type of a channel element

See also

spsc_open

spsc_nbrecv1

#define spsc_nbrecv1	(		C,
			DST )

Value:

spsc_nbrecv((C), 1, (DST))

Convenience macro for receiving a single item from a channel.

See also

spsc_nbrecv

spsc_nbsend1

#define spsc_nbsend1	(		C,
			SRC )

Value:

spsc_nbsend((C), 1, (SRC))

Convenience macro for sending a single item to a channel.

See also

spsc_nbsend

spsc_recv1

#define spsc_recv1	(		C,
			DST )

Value:

spsc_recv((C), 1, (DST))

Convenience macro for receiving a single item from a channel.

See also

spsc_recv

spsc_send1

#define spsc_send1	(		C,
			SRC )

Value:

spsc_send((C), 1, (SRC))

Convenience macro for sending a single item to a channel.

See also

spsc_send

Function Documentation

spsc_alloc()

struct spsc * spsc_alloc	(	size_t	nel,
		size_t	elsize )

Allocates a new spsc using malloc() and opens it.

Parameters

nel	The minimum number of elements the channel should be able to hold; must be a nonzero power of 2
elsize	The sizeof the type of a channel element

Returns

An owning pointer to a new spsc allocated using malloc(), or nil if nel is 0, or if elsize is 0 or not a power of 2, or if the memory allocation could not be made.

Exceptions

ENOMEM

if out of memory, as set by malloc()

See also

spsc_open

spsc_close()

enum chic_err spsc_close

(

struct spsc *

c

)

Closes a channel, forbidding any future send operations on it.

Parameters

c	The channel to close; must be non-nil

Returns

CHIC_OK if c is ready to be deallocated

CHIC_CHAN_UNREAD if c has unreceived items

Warning

Calling this function on any other thread other than the sole producer risks interrupting a pending send operation.

spsc_nbrecv()

enum chic_err spsc_nbrecv	(	struct spsc *restrict	c,
		size_t	n,
		size_t *restrict	n2,
		void *restrict	dst )

Receives whatever items are available from a channel.

Parameters

[in]	c	The channel to receive items from; must be non-nil
[in]	n	The number of items to receive
[out]	n2	If non-nil, will be incremented by the number of items that were actually received
[out]	dst	Where to receive the items into

Returns

CHIC_OK if one or more items were successfully received

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c, or if dst is nil

CHIC_CHAN_EMPTY if there is nothing to receive from the channel

CHIC_CHAN_CLOSED if chan is closed and there are no more items to receive

spsc_nbrecvv()

enum chic_err spsc_nbrecvv	(	struct spsc *restrict	c,
		size_t	n,
		size_t *restrict	n2,
			... )

Receives whatever items are available from a channel.

Parameters

	c	The channel to receive items from; must be non-nil
	n	The number of items to receive
[out]	n2	If non-nil, will be incremented by the number of items that were actually received
	...	Where to receive the items into

Returns

CHIC_OK if one or more items were successfully received

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c

CHIC_CHAN_EMPTY if there is nothing to receive from the channel

CHIC_CHAN_CLOSED if chan is closed and there are no more items to receive

spsc_nbsend()

enum chic_err spsc_nbsend	(	struct spsc *restrict	c,
		size_t	n,
		size_t *restrict	n2,
		void *restrict	src )

Sends whatever items will fit to a channel.

If the channel has less than n available item slots for writing, this function will send whatever items will fit. If there is no space available, this function will return 0.

Parameters

[in]	c	The channel to try to send items to; must be non-nil
[in]	n	The maximum number of items to try to send
[out]	n2	If non-nil, will be incremented by the number of items that were actually sent
[in]	src	Where to send the items from

Returns

CHIC_OK if one or more items were successfully sent

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c, or if src is nil

CHIC_CHAN_FULL if there is no room in the channel

CHIC_CHAN_CLOSED if chan is closed and can no longer be sent to

spsc_nbsendv()

enum chic_err spsc_nbsendv	(	struct spsc *restrict	c,
		size_t	n,
		size_t *restrict	n2,
			... )

Sends whatever items will fit to a channel.

If the channel has less than n available item slots for writing, this function will send whatever items will fit. If there is no space available, this function will return 0.

Parameters

	c	The channel to try to send items to; must be non-nil
	n	The maximum number of items to try to send
[out]	n2	If non-nil, will be incremented by the number of items that were actually sent
	...	Pointers to the items to send

Returns

CHIC_OK if one or more items were successfully sent

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c

CHIC_CHAN_FULL if there is no room in the channel

CHIC_CHAN_CLOSED if chan is closed and can no longer be sent to

spsc_nel()

size_t spsc_nel

(

struct spsc *

c

)

Gets the maximim number of elements a channel is capable of holding at once.

Parameters

c	The channel to get the capacity of; must be non-nil

Returns

The capacity of c

spsc_open()

size_t spsc_open	(	void *	c,
		size_t	nel,
		size_t	elsize )

Constructs a spsc in-place, or calculates the needed allocation size for one.

Parameters

[out]	c	The address at which to construct a spsc; may be nil
[in]	nel	The number of elements the channel can hold; must be a nonzero power of 2
[in]	elsize	The sizeof the type of an element

Returns

The allocation size necessary to construct a spsc with these parameters (if c was not nil, the size of the constructed spsc), or 0 if nel is 0, or if elsize is 0 or not a power of 2.

spsc_recv()

enum chic_err spsc_recv	(	struct spsc *restrict	c,
		size_t	n,
		void *restrict	dst )

Receives items from a channel.

If the channel does not have n or more available items ready to be received, this function will busy-wait until there are.

Parameters

[in]	c	The channel to receive items from; must be non-nil
[in]	n	The number of items to receive
[out]	dst	Where to receive the items into

Returns

CHIC_OK if the items were successfully received

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c, or if dst is nil

CHIC_CHAN_CLOSED if chan is closed and there are less than n items remaining to receive

spsc_recvv()

enum chic_err spsc_recvv	(	struct spsc *restrict	c,
		size_t	n,
			... )

Receives items from a channel.

If the channel does not have n or more available items ready to be received, this function will busy-wait until there are.

Parameters

c	The channel to receive items from; must be non-nil
n	The number of items to receive
...	Where to receive the items into

Returns

CHIC_OK if the items were successfully received

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c

CHIC_CHAN_CLOSED if chan is closed and there are less than n items remaining to receive

spsc_send()

enum chic_err spsc_send	(	struct spsc *restrict	c,
		size_t	n,
		void *restrict	src )

Sends items to a channel.

If the channel does not have enough free space to send all n items, this function will busy-wait until there are.

Parameters

c	The channel to send items to; must be non-nil
n	The number of items to send
src	Where to send the items from

Returns

CHIC_OK if the items were successfully sent

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c, or if src is nil

CHIC_CHAN_CLOSED if chan is closed and can no longer be sent to

spsc_sendv()

enum chic_err spsc_sendv	(	struct spsc *restrict	c,
		size_t	n,
			... )

Sends items to a channel.

If the channel does not have enough free space to send all n items, this function will busy-wait until there are.

Parameters

c	The channel to send items to; must be non-nil
n	The number of items to send
...	Pointers to the items to send

Returns

CHIC_OK if the items were successfully sent

CHIC_ARGS_INVAL if n is not within the range [0, nel], where nel is the capacity of c

CHIC_CHAN_CLOSED if chan is closed and can no longer be sent to