winstream.h File Reference

#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	sys_winstream
	Lockless shared memory byte stream IPC. More...

Functions
static struct sys_winstream *	sys_winstream_init (void *buf, int buflen)
	Construct a sys_winstream from a region of memory.
void	sys_winstream_write (struct sys_winstream *ws, const char *data, uint32_t len)
	Write bytes to a sys_winstream.
uint32_t	sys_winstream_read (struct sys_winstream *ws, uint32_t *seq, char *buf, uint32_t buflen)
	Read bytes from a sys_winstream.

Function Documentation

sys_winstream_init()

static struct sys_winstream * sys_winstream_init ( void *  buf, int  buflen  )

inlinestatic

Construct a sys_winstream from a region of memory.

This function initializes a sys_winstream in an arbitrarily-sized region of memory, returning the resulting object (which is guaranteed to be at the same address as the buffer). The memory must (obviously) be shared between the reader and writer, and all operations to it must be coherent and consistently ordered.

Parameters

buf	Pointer to a region of memory to contain the stream
buflen	Length of the buffer, must be large enough to contain the struct sys_winstream and at least one byte of data.

Returns

A pointer to an initialized sys_winstream (same address as the buf parameter).

sys_winstream_read()

uint32_t sys_winstream_read	(	struct sys_winstream *	ws,
		uint32_t *	seq,
		char *	buf,
		uint32_t	buflen
	)

Read bytes from a sys_winstream.

This function will read bytes from a sys_winstream into a specified buffer. It will always return in constant time, it does not block or engage in any kind of synchronization beyond memory ordering. The number of bytes read into the buffer will be returned, but note that it is possible that an underflow can occur if the writer gets ahead of our context. That situation can be detected via the sequence number returned via a pointer (i.e. if "*seq != old_seq + return_value", an underflow occurred and bytes were dropped).

Parameters

ws	A sys_winstream from which to read
seq	A pointer to an integer containing the last sequence number read from the stream, or zero to indicate "start of stream". It is updated in place and returned for future calls and for detecting underflows.
buf	A buffer into which to store the data read
buflen	The length of buf in bytes

Returns

The number of bytes written into the buffer

sys_winstream_write()

void sys_winstream_write	(	struct sys_winstream *	ws,
		const char *	data,
		uint32_t	len
	)

Write bytes to a sys_winstream.

This function writes the specified number of bytes into the stream. It will always return synchronously, it does not block or engage in any kind of synchronization beyond memory write ordering. Any bytes passed beyond what can be stored in the buffer will be silently dropped, but readers can detect their presence via the sequence number.

Parameters

ws	A sys_winstream to which to write
data	Pointer to bytes to be written
len	Number of bytes to write