Zero-copy

Tools for zero-copy send/receive operations. More...

Data Structures
struct	claim
	Claimed space for reading or writing directly into the internal ringbuffer of a channel. More...

Functions
bool	mpmc_send_init (struct mpmc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
size_t	mpmc_send_nbinit (struct mpmc *c, size_t n, struct claim *s)
	Claims up to an amount of space in the channel to be manually written into.
bool	mpmc_send_fini (struct mpmc *c, struct claim *s)
	Commits a claim, indicating the item slots within are finished being written to and are ready to be received.
bool	mpmc_send_nbfini (struct mpmc *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	mpmc_recv_init (struct mpmc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
size_t	mpmc_recv_nbinit (struct mpmc *c, size_t n, struct claim *r)
	Claims up to an amount of space in the channel to be manually read from.
bool	mpmc_recv_fini (struct mpmc *c, struct claim *r)
	Commits a claim, indicating the item slots within have been read from and are ready to be overwritten.
bool	mpmc_recv_nbfini (struct mpmc *c, struct claim *r)
	Tries to commit a claim, indicating the item slots within have been read from and are safe to be overwritten.
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_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	spmc_send_init (struct spmc *c, size_t n, struct claim *s)
	Claims space in the channel to be manually written into.
size_t	spmc_send_nbinit (struct spmc *c, size_t n, struct claim *s)
	Claims up to an amount of space in the channel to be manually written into.
bool	spmc_send_fini (struct spmc *c, struct claim *s)
	Commits a claim, indicating the item slots within have been written to and are ready to be received.
bool	spmc_recv_init (struct spmc *c, size_t n, struct claim *r)
	Claims space in the channel to be manually read from.
size_t	spmc_recv_nbinit (struct spmc *c, size_t n, struct claim *r)
	Claims up to an amount of space in the channel to be manually read from.
bool	spmc_recv_fini (struct spmc *c, struct claim *r)
	Commits a claim, indicating the item slots within have been read from and are ready to be overwritten.
bool	spmc_recv_nbfini (struct spmc *c, struct claim *r)
	Tries to commit a claim, indicating the item slots within have been read from and are safe to be overwritten.
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_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.

Detailed Description

Tools for zero-copy send/receive operations.

Function Documentation

mpmc_recv_fini()

bool mpmc_recv_fini	(	struct mpmc *	c,
		struct claim *	r )

Commits a claim, indicating the item slots within have been read from and are ready to be overwritten.

Claims for receiving must be committed according to their sequence number. If there are uncommitted claims for receiving sequenced prior to r, this function will busy-wait until this is no longer the case.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if r is empty

mpmc_recv_init()

bool mpmc_recv_init	(	struct mpmc *	c,
		size_t	n,
		struct claim *	r )

Claims space in the channel to be manually read from.

If the channel does not have n or more available item slots for reading, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n for reading directly from the channel; must be non-nil

Returns

Whether or not r was initialized. If false is returned, 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 no more items to receive
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpmc_recv_init, mpmc_recv_nbinit, mpmc_recv, mpmc_recvv, mpmc_nbrecv, or mpmc_nbrecvv until the claim s initialized by this function is committed via either mpmc_recv_fini or mpmc_recv_nbfini. Doing so will cause a deadlock as the thread will wait on itself.

mpmc_recv_nbfini()

bool mpmc_recv_nbfini	(	struct mpmc *	c,
		struct claim *	r )

Tries to commit a claim, indicating the item slots within have been read from and are safe to be overwritten.

Claims for receiving must be committed according to their sequence number. If there are uncommitted claims for receiving sequenced prior to c, this function will immediately return.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED	if c is empty
EAGAIN	if another consumer had an uncommitted claim for receiving sequenced prior to r

mpmc_recv_nbinit()

size_t mpmc_recv_nbinit	(	struct mpmc *	c,
		size_t	n,
		struct claim *	r )

Claims up to an amount of space in the channel to be manually read from.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The maximum number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n or less for reading directly from the channel; must be non-nil

Returns

The actual total length of r. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpmc_recv_init, mpmc_recv_nbinit, mpmc_recv, mpmc_recvv, mpmc_nbrecv, or mpmc_nbrecvv until the claim s initialized by this function is committed via either mpmc_recv_fini or mpmc_recv_nbfini. Doing so will cause a deadlock as the thread will wait on itself.

mpmc_send_fini()

bool mpmc_send_fini	(	struct mpmc *	c,
		struct claim *	s )

Commits a claim, indicating the item slots within are finished being written to and are ready to be received.

Claims for sending must be committed according to their sequence number. If there are uncommitted claims for sending sequenced prior to s, this function will busy-wait until this is no longer the case.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if c is empty

mpmc_send_init()

bool mpmc_send_init	(	struct mpmc *	c,
		size_t	n,
		struct claim *	s )

Claims space in the channel to be manually written into.

If the channel does not have n or more available item slots for writing, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n for writing directly into the channel; must be non-nil

Returns

Whether or not s was initialized. If false is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpmc_send_init, mpmc_send_nbinit, mpmc_send, mpmc_sendv, mpmc_nbsend, or mpmc_nbsendv until the claim s initialized by this function is committed via either mpmc_send_fini or mpmc_send_nbfini. Doing so will cause a deadlock as the thread will wait on itself.

mpmc_send_nbfini()

bool mpmc_send_nbfini	(	struct mpmc *	c,
		struct claim *	s )

Tries to commit a claim, indicating the item slots within have been written to and are ready to be received.

Claims for sending must be committed according to their sequence number. If there are uncommitted claims for sending sequenced prior to c, this function will immediately return.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED	if c is empty
EAGAIN	if another producer had an uncommitted claim for sending sequenced prior to s

mpmc_send_nbinit()

size_t mpmc_send_nbinit	(	struct mpmc *	c,
		size_t	n,
		struct claim *	s )

Claims up to an amount of space in the channel to be manually written into.

If the channel has less than n available item slots for writing, this function will claim whatever space is available. If there is no space available, this function will return an empty claim.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n or less for writing directly into the channel; must be non-nil

Returns

The actual total length of s. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpmc_send_init, mpmc_send_nbinit, mpmc_send, mpmc_sendv, mpmc_nbsend, or mpmc_nbsendv until the claim s initialized by this function is committed via either mpmc_send_fini or mpmc_send_nbfini. Doing so will cause a deadlock as the thread will wait on itself.

mpsc_recv_fini()

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.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if c is empty

mpsc_recv_init()

bool mpsc_recv_init	(	struct mpsc *	c,
		size_t	n,
		struct claim *	r )

Claims space in the channel to be manually read from.

If the channel does not have n or more available item slots for reading, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n for reading directly from the channel; must be non-nil

Returns

Whether or not r was initialized. If false is returned, 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 no more items to receive
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpsc_recv_init, mpsc_recv_nbinit, mpsc_recv, mpsc_recvv, mpsc_nbrecv, or mpsc_nbrecvv until the claim s initialized by this function is committed via mpsc_recv_fini. Doing so will cause a deadlock as the thread will wait on itself.

mpsc_recv_nbinit()

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.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The maximum number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n or less for reading directly from the channel; must be non-nil

Returns

The actual total length of r. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpsc_recv_init, mpsc_recv_nbinit, mpsc_recv, mpsc_recvv, mpsc_nbrecv, or mpsc_nbrecvv until the claim s initialized by this function is committed via mpsc_recv_fini. Doing so will cause a deadlock as the thread will wait on itself.

mpsc_send_fini()

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.

Claims for sending must be committed according to their sequence number. If there are uncommitted claims for sending sequenced prior to s, this function will busy-wait until this is no longer the case.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if c is empty

mpsc_send_init()

bool mpsc_send_init	(	struct mpsc *	c,
		size_t	n,
		struct claim *	s )

Claims space in the channel to be manually written into.

If the channel does not have n or more available item slots for writing, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n for writing directly into the channel; must be non-nil

Returns

Whether or not s was initialized. If false is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpsc_send_init, mpsc_send_nbinit, mpsc_send, mpsc_sendv, mpsc_nbsend, or mpsc_nbsendv until the claim s initialized by this function is committed via either mpsc_send_fini or mpsc_send_nbfini. Doing so is undefined behavior (which will most likely take the form of a deadlock).

mpsc_send_nbfini()

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.

Claims for sending must be committed according to their sequence number. If there are uncommitted claims for sending sequenced prior to c, this function will immediately return.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED	if c is empty
EAGAIN	if another producer had an uncommitted claim for sending sequenced prior to s

mpsc_send_nbinit()

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.

If the channel has less than n available item slots for writing, this function will claim whatever space is available. If there is no space available, this function will return an empty claim.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n or less for writing directly into the channel; must be non-nil

Returns

The actual total length of s. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of mpsc_send_init, mpsc_send_nbinit, mpsc_send, mpsc_sendv, mpsc_nbsend, or mpsc_nbsendv until the claim s initialized by this function is committed via either mpsc_send_fini or mpsc_send_nbfini. Doing so is undefined behavior (which will most likely take the form of a deadlock).

spmc_recv_fini()

bool spmc_recv_fini	(	struct spmc *	c,
		struct claim *	r )

Commits a claim, indicating the item slots within have been read from and are ready to be overwritten.

Claims for receiving must be committed according to their sequence number. If there are uncommitted claims for receiving sequenced prior to r, this function will busy-wait until this is no longer the case.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if r is empty

spmc_recv_init()

bool spmc_recv_init	(	struct spmc *	c,
		size_t	n,
		struct claim *	r )

Claims space in the channel to be manually read from.

If the channel does not have n or more available item slots for reading, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n for reading directly from the channel; must be non-nil

Returns

Whether or not r was initialized. If false is returned, 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 no more items to receive
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spmc_recv_init, spmc_recv_nbinit, spmc_recv, spmc_recvv, spmc_nbrecv, or spmc_nbrecvv until the claim s initialized by this function is committed via either spmc_recv_fini or spmc_recv_nbfini. Doing so is undefined behavior (which will most likely take the form of a deadlock).

spmc_recv_nbfini()

bool spmc_recv_nbfini	(	struct spmc *	c,
		struct claim *	r )

Tries to commit a claim, indicating the item slots within have been read from and are safe to be overwritten.

Claims for receiving must be committed according to their sequence number. If there are uncommitted claims for receiving sequenced prior to c, this function will immediately return.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED	if c is empty
EAGAIN	if another consumer had an uncommitted claim for receiving sequenced prior to r

spmc_recv_nbinit()

size_t spmc_recv_nbinit	(	struct spmc *	c,
		size_t	n,
		struct claim *	r )

Claims up to an amount of space in the channel to be manually read from.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The maximum number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n or less for reading directly from the channel; must be non-nil

Returns

The actual total length of r. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spmc_recv_init, spmc_recv_nbinit, spmc_recv, spmc_recvv, spmc_nbrecv, or spmc_nbrecvv until the claim s initialized by this function is committed via either spmc_recv_fini or spmc_recv_nbfini. Doing so is undefined behavior (which will most likely take the form of a deadlock).

spmc_send_fini()

bool spmc_send_fini	(	struct spmc *	c,
		struct claim *	s )

Commits a claim, indicating the item slots within have been written to and are ready to be received.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if c is empty

spmc_send_init()

bool spmc_send_init	(	struct spmc *	c,
		size_t	n,
		struct claim *	s )

Claims space in the channel to be manually written into.

If the channel does not have n or more available item slots for writing, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n for writing directly into the channel; must be non-nil

Returns

Whether or not s was initialized. If false is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spmc_send_init, spmc_send_nbinit, spmc_send, spmc_sendv, spmc_nbsend, or spmc_nbsendv until the claim s initialized by this function is committed via spmc_send_fini. Doing so will cause a deadlock as the thread will wait on itself.

spmc_send_nbinit()

size_t spmc_send_nbinit	(	struct spmc *	c,
		size_t	n,
		struct claim *	s )

Claims up to an amount of space in the channel to be manually written into.

If the channel has less than n available item slots for writing, this function will claim whatever space is available. If there is no space available, this function will return an empty claim.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n or less for writing directly into the channel; must be non-nil

Returns

The actual total length of s. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spmc_send_init, spmc_send_nbinit, spmc_send, spmc_sendv, spmc_nbsend, or spmc_nbsendv until the claim s initialized by this function is committed via spmc_send_fini. Doing so will cause a deadlock as the thread will wait on itself.

spsc_recv_fini()

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.

Parameters

c	The channel in which to commit the claim; must be non-nil
r	The claim to commit as received; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

ECANCELED

if c is empty

spsc_recv_init()

bool spsc_recv_init	(	struct spsc *	c,
		size_t	n,
		struct claim *	r )

Claims space in the channel to be manually read from.

If the channel does not have n or more available item slots for reading, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n for reading directly from the channel; must be non-nil

Returns

Whether or not r was initialized. If false is returned, 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 no more items to receive
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spsc_recv_init, spsc_recv_nbinit, spsc_recv, spsc_recvv, spsc_nbrecv, or spsc_nbrecvv until the claim s initialized by this function is committed via spsc_recv_fini. Doing so will cause a deadlock as the thread will wait on itself.

spsc_recv_nbinit()

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.

Parameters

[in]	c	The channel to claim space for receiving from; must be non-nil
[in]	n	The maximum number of item slots to claim for reading
[out]	r	A claim to initialize with one or two slices with total length n or less for reading directly from the channel; must be non-nil

Returns

The actual total length of r. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spsc_recv_init, spsc_recv_nbinit, spsc_recv, spsc_recvv, spsc_nbrecv, or spsc_nbrecvv until the claim s initialized by this function is committed via spsc_recv_fini. Doing so will cause a deadlock as the thread will wait on itself.

spsc_send_fini()

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.

Claims for sending must be committed according to their sequence number. If there are uncommitted claims for sending sequenced prior to c, this function will immediately return.

Parameters

c	The channel in which to commit the claim; must be non-nil
s	The claim to commit as sent; must be non-nil. If this function succeeds, claim_consume will be called on this claim.

Returns

Whether or not the claim was committed. If false, errno is set to indicate the reason why.

Exceptions

EINVAL	if either of c or s are nil
ECANCELED	if c is empty

spsc_send_init()

bool spsc_send_init	(	struct spsc *	c,
		size_t	n,
		struct claim *	s )

Claims space in the channel to be manually written into.

If the channel does not have n or more available item slots for writing, this function will busy-wait until there are.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n for writing directly into the channel; must be non-nil

Returns

Whether or not s was initialized. If false is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spsc_send_init, spsc_send_nbinit, spsc_send, spsc_sendv, spsc_nbsend, or spsc_nbsendv until the claim s initialized by this function is committed via spsc_send_fini. Doing so will cause a deadlock as the thread will wait on itself.

spsc_send_nbinit()

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.

If the channel has less than n available item slots for writing, this function will claim whatever space is available. If there is no space available, this function will return an empty claim.

Parameters

[in]	c	The channel to claim space for sending into; must be non-nil
[in]	n	The number of item slots to claim for writing
[out]	s	A claim to initialize with one or two slices with total length n or less for writing directly into the channel; must be non-nil

Returns

The actual total length of s. If 0 is returned, 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
EOVERFLOW	if the successfully claimed item slots wrap around the end of the channel's internal ringbuffer

Warning

Any thread that calls this function must not call any of spsc_send_init, spsc_send_nbinit, spsc_send, spsc_sendv, spsc_nbsend, or spsc_nbsendv until the claim s initialized by this function is committed via spsc_send_fini. Doing so will cause a deadlock as the thread will wait on itself.