mpsc.h File Reference

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

#include "claim.h"
#include "err.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.
enum chic_err	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.
enum chic_err	mpsc_send_init (struct mpsc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
enum chic_err	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.
void	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.
enum chic_err	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.
enum chic_err	mpsc_send (struct mpsc *restrict c, size_t n, void *restrict src)
	Sends items to a channel.
enum chic_err	mpsc_nbsend (struct mpsc *restrict c, size_t n, size_t *restrict n2, void *restrict src)
	Sends whatever items will fit to a channel.
enum chic_err	mpsc_sendv (struct mpsc *restrict c, size_t n,...)
	Sends items to a channel.
enum chic_err	mpsc_nbsendv (struct mpsc *restrict c, size_t n, size_t *restrict n2,...)
	Sends whatever items will fit to a channel.
enum chic_err	mpsc_recv_init (struct mpsc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
enum chic_err	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.
void	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.
enum chic_err	mpsc_recv (struct mpsc *restrict c, size_t n, void *restrict dst)
	Receives items from a channel.
enum chic_err	mpsc_nbrecv (struct mpsc *restrict c, size_t n, size_t *restrict n2, void *restrict dst)
	Receives whatever items are available from a channel.
enum chic_err	mpsc_recvv (struct mpsc *restrict c, size_t n,...)
	Receives items from a channel.
enum chic_err	mpsc_nbrecvv (struct mpsc *restrict c, size_t n, size_t *restrict n2,...)
	Receives whatever items are available from a channel.

Detailed Description

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

mpsc_open

mpsc_close()

enum chic_err 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

CHIC_OK if c is ready to be deallocated

CHIC_CHAN_UNREAD if c has unreceived items

mpsc_nbrecv()

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

mpsc_nbrecvv()

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

mpsc_nbsend()

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

mpsc_nbsendv()

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

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), or 0 if nel is 0, or if elsize is 0 or not a power of 2.

mpsc_recv()

enum chic_err 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

[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

mpsc_recvv()

enum chic_err 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

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

mpsc_send()

enum chic_err 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

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

mpsc_sendv()

enum chic_err 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

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