claim Struct Reference

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

#include <claim.h>

Data Fields
size_t	seq
	The sequence number of this claim.
size_t	len [2]
	The lengths of the two slices.
char *	ptr [2]
	The pointers to the start of the two slices.

Detailed Description

Claimed space for reading or writing directly into the internal ringbuffer of a channel.

All send/receive channel operations internally perform the following steps:

1. Claim empty space (for sending) or sent items (for receiving)
2. Copy items into that space (if sending) or copy items from that space (receiving)
3. Commit that claim, notifying receivers there is new items (if sending) or notifying senders there is empty space available (if receiving)

However, claims can be used directly to enable zero-copy operations. Instead of copying data into and out of the channel, that data is calculated or constructed directly inside the channel and read directly from the channel. Claims can be obtained from low-level *init() channel functions (such as mpmc_send_init) and committed through low-level *fini() channel functions (such as mpmc_send_fini).

This claimed space consists of one or two "slices" of its origin channel's internal ringbuffer; that is, one or two contiguous memory regions which can be read from or written to directly.

Since these slices refer to regions of the channel's internal ringbuffer, there is a chance that a claim may "wrap around" the end of the ringbuffer. For example, if the ringbuffer has a maximum capacity of 4 items, and 3 items are sent, then 1 item is received, there are two empty spaces that are free to be claimed for sending.

[ |x|x| ]
       ^ptr[0], len[0] = 1
 ^ptr[1], len[1] = 1

However, one of these spaces is at the end of the ringbuffer, while the other is at the start; these spaces are not contiguous. In this case, it is valid to claim those 2 spaces for sending, but since they are not contiguous, the claim will be "split" and the second slice of the claim will be populated.

A claim must be committed only into the channel it was obtained from.

Field Documentation

len

size_t claim::len[2]

The lengths of the two slices.

If this claim is valid, [0] should always have a nonzero length. If this claim wraps around the origin channel's internal ringbuffer (that is to say, claim_is_split is true), [1] will have a nonzero length.

ptr

char* claim::ptr[2]

The pointers to the start of the two slices.

To meaningfully use these, they should be cast to a pointer to the expected type. For example, for a claim originating from a channel of doubles:

struct claim c;
// populate `c` with a channel operation
double *p0 = (double*)(c.ptr[0]);
double *p1 = (double*)(c.ptr[1]);
// read to and write from `p0` and `p1`

---

The documentation for this struct was generated from the following file:

• include/claim.h