mpsc.h File Reference

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

#include "claim.h"

Go to the source code of this file.

Macros
#define	make_mpsc(N, T)
	Convenience macro for allocating a new mpsc.
#define	sizeof_mpsc(N, T)
	Convenience macro for calculating the size of a mpsc with certain parameters.
#define	mpsc_send1(C, SRC)
	Convenience macro for sending a single item to a channel.
#define	mpsc_nbsend1(C, SRC)
	Convenience macro for sending a single item to a channel.
#define	mpsc_recv1(C, DST)
	Convenience macro for receiving a single item from a channel.
#define	mpsc_nbrecv1(C, DST)
	Convenience macro for receiving a single item from a channel.

Functions
size_t	mpsc_open (void *c, size_t nel, size_t elsize)
	Constructs a mpsc in-place, or calculates the needed allocation size for one.
struct mpsc *	mpsc_alloc (size_t nel, size_t elsize)
	Allocates a new mpsc using malloc() and opens it.
bool	mpsc_close (struct mpsc *c)
	Closes a channel, forbidding any future send operations on it.
size_t	mpsc_nel (struct mpsc *c)
	Gets the maximim number of elements a channel is capable of holding at once.
bool	mpsc_send_init (struct mpsc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
size_t	mpsc_send_nbinit (struct mpsc *c, size_t n, struct claim *s)
	Claims up to an amount of space in the channel to be manually written into.
bool	mpsc_send_fini (struct mpsc *c, struct claim *s)
	Commits a claim, indicating the item slots within are finished being written to and are ready to be received.
bool	mpsc_send_nbfini (struct mpsc *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	mpsc_send (struct mpsc *restrict c, size_t n, void *restrict src)
	Sends items to a channel.
size_t	mpsc_nbsend (struct mpsc *restrict c, size_t n, void *restrict src)
	Sends whatever items will fit to a channel.
bool	mpsc_sendv (struct mpsc *restrict c, size_t n,...)
	Sends items to a channel.
size_t	mpsc_nbsendv (struct mpsc *restrict c, size_t n,...)
	Sends whatever items will fit to a channel.
bool	mpsc_recv_init (struct mpsc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
size_t	mpsc_recv_nbinit (struct mpsc *c, size_t n, struct claim *r)
	Claims up to an amount of space in the channel to be manually read from.
bool	mpsc_recv_fini (struct mpsc *c, struct claim *r)
	Commits a claim, indicating the item slots within have been read from and are safe to be overwritten.
bool	mpsc_recv (struct mpsc *restrict c, size_t n, void *restrict dst)
	Receives items from a channel.
size_t	mpsc_nbrecv (struct mpsc *restrict c, size_t n, void *restrict dst)
	Receives whatever items are available from a channel.
bool	mpsc_recvv (struct mpsc *restrict c, size_t n,...)
	Receives items from a channel.
size_t	mpsc_nbrecvv (struct mpsc *restrict c, size_t n,...)
	Receives whatever items are available from a channel.

Detailed Description

Multiple-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_mpsc

#define make_mpsc	(		N,
			T )

Value:

mpsc_alloc((N), sizeof(T))

Convenience macro for allocating a new mpsc.

Parameters

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

See also

mpsc_alloc

mpsc_nbrecv1

#define mpsc_nbrecv1	(		C,
			DST )

Value:

mpsc_nbrecv((C), 1, (DST))

Convenience macro for receiving a single item from a channel.

See also

mpsc_nbrecv

mpsc_nbsend1

#define mpsc_nbsend1	(		C,
			SRC )

Value:

mpsc_nbsend((C), 1, (SRC))

Convenience macro for sending a single item to a channel.

See also

mpsc_nbsend

mpsc_recv1

#define mpsc_recv1	(		C,
			DST )

Value:

mpsc_recv((C), 1, (DST))

Convenience macro for receiving a single item from a channel.

See also

mpsc_recv

mpsc_send1

#define mpsc_send1	(		C,
			SRC )

Value:

mpsc_send((C), 1, (SRC))

Convenience macro for sending a single item to a channel.

See also

mpsc_send

sizeof_mpsc

#define sizeof_mpsc	(		N,
			T )

Value:

mpsc_open(NULL, (N), sizeof(T))

Convenience macro for calculating the size of a mpsc 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

mpsc_open

Function Documentation

mpsc_alloc()

struct mpsc * mpsc_alloc	(	size_t	nel,
		size_t	elsize )

Allocates a new mpsc 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 mpsc 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

mpsc_open

mpsc_close()

bool mpsc_close

(

struct mpsc *

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

mpsc_nbrecv()

size_t mpsc_nbrecv	(	struct mpsc *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

mpsc_nbrecvv()

size_t mpsc_nbrecvv	(	struct mpsc *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

mpsc_nbsend()

size_t mpsc_nbsend	(	struct mpsc *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

mpsc_nbsendv()

size_t mpsc_nbsendv	(	struct mpsc *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

mpsc_nel()

size_t mpsc_nel

(

struct mpsc *

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

mpsc_open()

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

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

Parameters

[out]	c	The address at which to construct a mpsc; 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 mpsc with these parameters (if c was not nil, the size of the constructed mpsc). 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

mpsc_recv()

bool mpsc_recv	(	struct mpsc *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

mpsc_recvv()

bool mpsc_recvv	(	struct mpsc *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

mpsc_send()

bool mpsc_send	(	struct mpsc *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

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

mpsc_sendv()

bool mpsc_sendv	(	struct mpsc *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