libxchg
Public Member Functions
xchg_channel Struct Reference

Represents a lock-free communication device backed by shared memory buffers which can be manipulated using the xchg_channel_* family of functions. More...

#include <xchg.h>

Public Member Functions

bool xchg_channel_init (struct xchg_channel *channel, size_t sz_message, char *ingress, size_t sz_ingress, char *egress, size_t sz_egress)
 Configures channel to use ingress of size sz_ingress and egress of size sz_egress as underlying shared memory for receiving and sending messages of size sz_message. More...
 
bool xchg_channel_prepare (struct xchg_channel *channel, struct xchg_message *message)
 Prepares message with writable backing memory from channel, allowing the caller to construct a message payload and then send it into the channel via xchg_channel_send. More...
 
bool xchg_channel_send (struct xchg_channel *channel, const struct xchg_message *message)
 Sends message (previously initialized via xchg_channel_prepare) into channel. More...
 
bool xchg_channel_receive (struct xchg_channel *channel, struct xchg_message *message)
 Receives the next available message from channel into message, allowing the caller to read the message payload and then return it to the channel via xchg_channel_return. More...
 
bool xchg_channel_return (struct xchg_channel *channel, const struct xchg_message *message)
 Returns the backing memory of message (previously initialized via xchg_channel_receive) to channel. More...
 
const char * xchg_channel_strerror (const struct xchg_channel *channel)
 Provides a static string describing the error that occurred during the last operation on channel More...
 

Detailed Description

Represents a lock-free communication device backed by shared memory buffers which can be manipulated using the xchg_channel_* family of functions.

Note
This type should be treated as opaque.

Member Function Documentation

◆ xchg_channel_init()

bool xchg_channel_init ( struct xchg_channel channel,
size_t  sz_message,
char *  ingress,
size_t  sz_ingress,
char *  egress,
size_t  sz_egress 
)

Configures channel to use ingress of size sz_ingress and egress of size sz_egress as underlying shared memory for receiving and sending messages of size sz_message.

Parameters
[in]channelpointer to an xchg_channel structure
[in]sz_messagemaximum size, in bytes, of messages that are consumed or produced by this channel
[in]ingresspointer to the shared memory buffer containing messages to be consumed by this channel
[in]sz_ingresssize, in bytes, of the ingress memory buffer
[in]egresspointer to the shared memory buffer into which messages can be produced by this channel
[in]sz_egresssize, in bytes, of the egress memory buffer
Returns
true if the provided xchg_channel was initialized, or false if invalid arguments were provided
Note
The sz_message parameter must be a power-of-two.
The sz_ingress and sz_egress parameters must be a power-of-two, plus an additional 2*sizeof(void *) bytes for ring accounting overhead.
The sz_message parameter must not be larger than either sz_ingress or sz_egress.
While the ingress and egress parameters are both optional, the caller must provide at least one of them.

◆ xchg_channel_prepare()

bool xchg_channel_prepare ( struct xchg_channel channel,
struct xchg_message message 
)

Prepares message with writable backing memory from channel, allowing the caller to construct a message payload and then send it into the channel via xchg_channel_send.

Parameters
[in]channelpointer to an xchg_channel structure
[in]messagepointer to an xchg_message to be initialized
Returns
true if the provided xchg_message was prepared, otherwise false

◆ xchg_channel_receive()

bool xchg_channel_receive ( struct xchg_channel channel,
struct xchg_message message 
)

Receives the next available message from channel into message, allowing the caller to read the message payload and then return it to the channel via xchg_channel_return.

Parameters
[in]channelpointer to an xchg_channel structure
[in]messagepointer to an xchg_message to be initialized
Returns
true if a message was received into the provided xchg_message, otherwise false

◆ xchg_channel_return()

bool xchg_channel_return ( struct xchg_channel channel,
const struct xchg_message message 
)

Returns the backing memory of message (previously initialized via xchg_channel_receive) to channel.

Parameters
[in]channelpointer to an xchg_channel structure
[in]messagepointer to an xchg_message which was previously initialized by xchg_channel_receive
Returns
true if the provided xchg_message was returned, otherwise false

◆ xchg_channel_send()

bool xchg_channel_send ( struct xchg_channel channel,
const struct xchg_message message 
)

Sends message (previously initialized via xchg_channel_prepare) into channel.

Parameters
[in]channelpointer to an xchg_channel structure
[in]messagepointer to an xchg_message which was previously initialized by xchg_channel_prepare
Returns
true if the provided xchg_message was sent, otherwise false

◆ xchg_channel_strerror()

const char * xchg_channel_strerror ( const struct xchg_channel channel)

Provides a static string describing the error that occurred during the last operation on channel

Parameters
[in]channelpointer to an xchg_channel structure
Returns
pointer to a static string describing the error that occurred during the last operation on channel