spsc.h File Reference

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

#include "claim.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.
bool	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.
bool	spsc_send_init (struct spsc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
size_t	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.
bool	spsc_send_fini (struct spsc *c, struct claim *s)
	Tries to commit a claim, indicating the item slots within have been written to and are ready to be received.
bool	spsc_send (struct spsc *restrict c, size_t n, void *restrict src)
	Sends items to a channel.
size_t	spsc_nbsend (struct spsc *restrict c, size_t n, void *restrict src)
	Sends whatever items will fit to a channel.
bool	spsc_sendv (struct spsc *restrict c, size_t n,...)
	Sends items to a channel.
size_t	spsc_nbsendv (struct spsc *restrict c, size_t n,...)
	Sends whatever items will fit to a channel.
bool	spsc_recv_init (struct spsc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
size_t	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.
bool	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.
bool	spsc_recv (struct spsc *restrict c, size_t n, void *restrict dst)
	Receives items from a channel.
size_t	spsc_nbrecv (struct spsc *restrict c, size_t n, void *restrict dst)
	Receives whatever items are available from a channel.
bool	spsc_recvv (struct spsc *restrict c, size_t n,...)
	Receives items from a channel.
size_t	spsc_nbrecvv (struct spsc *restrict c, size_t n,...)
	Receives whatever items are available from a channel.

Detailed Description

Single-producer, single-consumer channel.

Author

Fawn rubie.nosp@m.fawn.nosp@m.@gmai.nosp@m.l.co.nosp@m.m

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 there was an error. If nil is returned, errno is set to indicate the reason why.

Exceptions

EINVAL	if nel is 0, or if elsize is 0 or not a power of 2
ENOMEM	if out of memory

See also

spsc_open

spsc_close()

bool 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

Whether or not the channel is ready to be deallocated. If false is returned, errno is set to indicate the reason why.

Exceptions

EBUSY

if chan has unreceived items

Warning

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

spsc_nbrecv()

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

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
dst	Where to receive the items into

Returns

How many items were received. If 0, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c, or if dst is nil
ENOMSG	if there is nothing to receive from the channel
EPIPE	if chan is closed and there are no more items to receive

spsc_nbrecvv()

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

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
...	Where to receive the items into

Returns

How many items were received. If 0, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c
ENOMSG	if there is nothing to receive from the channel
EPIPE	if chan is closed and there are no more items to receive

spsc_nbsend()

size_t spsc_nbsend	(	struct spsc *restrict	c,
		size_t	n,
		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

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

Returns

How many items were sent. If 0, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c, or if src is nil
ENOBUFS	if there is no room in the channel
EPIPE	if chan is closed and can no longer be sent to

spsc_nbsendv()

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

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
...	Pointers to the items to send

Returns

How many items were sent. If 0, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c
ENOBUFS	if there is no room in the channel
EPIPE	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). If there was an error, returns 0. If 0 is returned, errno is set to indicate the reason why.

Exceptions

EINVAL

if nel is 0, or if elsize is 0 or not a power of 2

spsc_recv()

bool 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

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

Returns

Whether or not the items were received. If false, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c, or if dst is nil
EPIPE	if chan is closed and there are less than n items remaining to receive

spsc_recvv()

bool 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

Whether or not the items were received. If false, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c
EPIPE	if chan is closed and there are less than n items remaining to receive

spsc_send()

bool 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; must be non-nil
src	Where to send the items from

Returns

Whether or not the items were sent. If false, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c, or if src is nil
EPIPE	if chan is closed and can no longer be sent to

spsc_sendv()

bool 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

Whether or not the items were sent. If false, errno is set to indicate the reason why.

Exceptions

EINVAL	if n is not within the range [0, nel], where nel is the capacity of c
EPIPE	if chan is closed and can no longer be sent to