iobuf.h File Reference

Generic I/O buffer implementation. More...

#include <wfio/type.h>

Go to the source code of this file.

Classes
struct	wfio_iobuf_t
	A generic I/O buffer. More...
class	wfio::IOBuf
	A C++ wrapper for a wfio_iobuf_t. More...

Namespaces
	wfio
	The root namespace for WFIO.

Typedefs
typedef WFIO_C_BEGIN enum wfio_iobuf_flags_t	wfio_iobuf_flags_t
	A type representing a wfio_iobuf_t's flags.
typedef size_t(*	wfio_iobuf_source_callback_t) (void *src, void *buf, size_t len, int *error)
	A callback for wfio_iobuf_source(). More...
typedef size_t(*	wfio_iobuf_sink_callback_t) (void *dest, const void *buf, size_t len, int *error)
	A callback for wfio_iobuf_sink(). More...
typedef struct wfio_iobuf_t	wfio_iobuf_t
	A generic I/O buffer. More...

Enumerations
enum	wfio_iobuf_flags_t { WFIO_IOBUF_FLIPPED = 0x1, WFIO_IOBUF_SHARED = 0x2, WFIO_IOBUF_SHARED_RD = WFIO_IOBUF_SHARED, WFIO_IOBUF_SHARED_WR = WFIO_IOBUF_SHARED | WFIO_IOBUF_FLIPPED }
	A type representing a wfio_iobuf_t's flags. More...

Functions
WFIO_INLINE void *	wfio_iobuf_rawdata (wfio_iobuf_t *buf)
	Obtain access to the raw data memory associated with this buffer. More...
WFIO_ALWAYS_INLINE size_t	wfio_iobuf_remain (wfio_iobuf_t *buf)
	Obtain the number of bytes left in the buffer. More...
WFIO_ALWAYS_INLINE size_t	wfio_iobuf_remainElem (wfio_iobuf_t *buf, size_t sz)
	Obtain the number of elements left in the buffer. More...
WFIO_DLL int	wfio_iobuf_clear (wfio_iobuf_t *buf, int *error)
	Discard all data currently in current facet of this buffer. More...
WFIO_DLL wfio_iobuf_t *	wfio_iobuf_alloc (size_t capacity, int *error)
	Create a new exclusive IO buffer. More...
WFIO_DLL wfio_iobuf_t *	wfio_iobuf_allocSplit (size_t f0, size_t f1, int *error)
	Create a new shared IO buffer with split facet sizes. More...
WFIO_DLL wfio_iobuf_t *	wfio_iobuf_allocShared (size_t capacity, int *error)
	Create a new shared IO buffer with evenly-split facet sizes. More...
WFIO_DLL int	wfio_iobuf_acquire (wfio_iobuf_t *buf)
	Acquire the buffer buf. More...
WFIO_DLL void	wfio_iobuf_free (wfio_iobuf_t *buf)
	Release the buffer buf. More...
WFIO_DLL int	wfio_iobuf_flip (wfio_iobuf_t *buf, int *error)
	Flip the buffer buf. More...
WFIO_ALWAYS_INLINE int	wfio_iobuf_notRead (const wfio_iobuf_t *buf)
	Determine if the buf is shared and not using the read buffer. More...
WFIO_ALWAYS_INLINE int	wfio_iobuf_notWrite (const wfio_iobuf_t *buf)
	Determine if the buf is shared and not using the write buffer. More...
WFIO_INLINE int	wfio_iobuf_ensureRead (wfio_iobuf_t *buf, int *error)
	Ensure that buf is using the read buffer. More...
WFIO_INLINE int	wfio_iobuf_ensureWrite (wfio_iobuf_t *buf, int *error)
	Ensure that buf is using the write buffer. More...
WFIO_DLL size_t	wfio_iobuf_read (wfio_iobuf_t *buf, void *dest, size_t sz, size_t elem, int *error)
	Consume elements from the buffer buf. More...
WFIO_DLL size_t	wfio_iobuf_readbV (wfio_iobuf_t *buf, void *dest, size_t len, int *error)
	Consume bytes from the buffer buf. More...
WFIO_INLINE int	wfio_iobuf_readb (wfio_iobuf_t *buf, int *error)
	Consume a single from the buffer buf. More...
WFIO_DLL size_t	wfio_iobuf_write (wfio_iobuf_t *buf, const void *src, size_t sz, size_t elem, int *error)
	Emplace bytes into the buffer buf. More...
WFIO_DLL size_t	wfio_iobuf_writebV (wfio_iobuf_t *buf, const void *src, size_t len, int *error)
	Emplace bytes into the buffer buf. More...
WFIO_INLINE int	wfio_iobuf_writeb (wfio_iobuf_t *buf, char c, int *error)
	Consume a single from the buffer buf. More...
WFIO_DLL int	wfio_iobuf_forceReorganize (wfio_iobuf_t *buf, int *error)
	Force reoganization of this buffer. More...
WFIO_DLL size_t	wfio_iobuf_source (wfio_iobuf_t *buf, size_t sz, size_t elem, void *src, wfio_iobuf_source_callback_t cb, int *error)
	Source new elements into buf from src. More...
WFIO_DLL size_t	wfio_iobuf_sourcebV (wfio_iobuf_t *buf, size_t len, void *src, wfio_iobuf_source_callback_t cb, int *error)
	Source new bytes into buf from src. More...
WFIO_ALWAYS_INLINE size_t	wfio_iobuf_fill (wfio_iobuf_t *buf, void *dest, wfio_iobuf_source_callback_t cb, int *error)
	Fill this buffer from src. More...
WFIO_DLL size_t	wfio_iobuf_sink (wfio_iobuf_t *buf, size_t sz, size_t elem, void *dest, wfio_iobuf_sink_callback_t cb, int *error)
	Sink new elements from buf into dest. More...
WFIO_DLL size_t	wfio_iobuf_sinkbV (wfio_iobuf_t *buf, size_t len, void *dest, wfio_iobuf_sink_callback_t cb, int *error)
	Sink new bytes from buf into dest. More...
WFIO_ALWAYS_INLINE size_t	wfio_iobuf_empty (wfio_iobuf_t *buf, void *dest, wfio_iobuf_sink_callback_t cb, int *error)
	Empty this buffer into src. More...

Detailed Description

Generic I/O buffer implementation.

Author

Phillip Kilgore

Since

0.0.1

Typedef Documentation

wfio_iobuf_sink_callback_t

typedef size_t(* wfio_iobuf_sink_callback_t) (void *dest, const void *buf, size_t len, int *error)

A callback for wfio_iobuf_sink().

Parameters

dest	The destination object.
buf	The buffer to write from.
len	The maximum number of bytes to write from the buffer.
error	An optional error indicator.

Returns

The number of bytes read into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_source_callback_t

typedef size_t(* wfio_iobuf_source_callback_t) (void *src, void *buf, size_t len, int *error)

A callback for wfio_iobuf_source().

Parameters

src	The source object.
buf	The buffer to read into.
len	The maximum number of bytes to read into the buffer.
error	An optional error indicator.

Returns

The number of bytes read into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_t

typedef struct wfio_iobuf_t wfio_iobuf_t

A generic I/O buffer.

An wfio_iobuf_t represents a generic circular buffer that can be used to implement buffering operations on devices or other objects which do not immediately provide it.

An wfio_iobuf_t may be allocated in two ways: as an exclusive buffer which allocates the entire memory to a single buffer, or as a shared double-buffer. To allocate an exclusive buffer, use the wfio_iobuf_alloc() function.

A shared buffer divides its memory into two facets which are respectively called facet 0 and facet 1. Facet 0 occupies the lower portion of memory, whereas facet 1 occupies the upper portion. Which facet is in use may be interrogated by the WFIO_IOBUF_FLIPPED bit; if it is set, then facet 1 is in use; otherwise, facet 0 is in use.

Shared buffers are extremely useful for implementing read-write devices so that the contents of the read or write buffer are not lost whenever performing the opposing operation.

Enumeration Type Documentation

wfio_iobuf_flags_t

enum wfio_iobuf_flags_t

A type representing a wfio_iobuf_t's flags.

Enumerator
WFIO_IOBUF_FLIPPED	The IO buffer has been flipped.
WFIO_IOBUF_SHARED	The IO buffer is shared.
WFIO_IOBUF_SHARED_RD	The buffer is shared but not yet flipped. This "flag" is used to indicate that the "read" buffer is currently in use by a shared buffer. Facet 0 is arbitrarily designated as the read buffer for this purpose.
WFIO_IOBUF_SHARED_WR	The buffer is shared and has been flipped. This "flag" is used to indicate that the "write" buffer is currently in use by a shared buffer. Facet 1 is arbitrarily designated as the write buffer for this purpose.

Function Documentation

wfio_iobuf_acquire()

WFIO_DLL int wfio_iobuf_acquire

(

wfio_iobuf_t *

buf

)

Acquire the buffer buf.

This function requests joint ownership of buf.

Parameters

buf	The buffer to acquire.

Returns

Nonzero if the buffer was successfully acquired; otherwise, zero.

wfio_iobuf_alloc()

WFIO_DLL wfio_iobuf_t* wfio_iobuf_alloc	(	size_t	capacity,
		int *	error
	)

Create a new exclusive IO buffer.

Parameters

capacity	The requested maximum capacity of the new buffer.
error	An optional error indicator.

Returns

A valid wfio_iobuf_t* instance on success; otherwise, NULL.

wfio_iobuf_allocShared()

WFIO_DLL wfio_iobuf_t* wfio_iobuf_allocShared	(	size_t	capacity,
		int *	error
	)

Create a new shared IO buffer with evenly-split facet sizes.

This function creates a shared buffer with the capacity split evenly between the two facets. If the capacity is one, then this creates a two-byte buffer with each facet having a size of 1 byte. Otherwise, the capacity is halved and the excess goes to the read buffer.

Parameters

capacity	The requested maximum capacity of the new buffer.
error	An optional error indicator.

Returns

A valid wfio_iobuf_t* instance on success; otherwise, NULL.

wfio_iobuf_allocSplit()

WFIO_DLL wfio_iobuf_t* wfio_iobuf_allocSplit	(	size_t	f0,
		size_t	f1,
		int *	error
	)

Create a new shared IO buffer with split facet sizes.

This function creates a shared buffer with split facet sizes f0 and f1 (corresponding to the first and second facets respectively).

Parameters

f0	The capacity of the first facet.
f1	The capacity of the first facet.
error	An optional error indicator.

Returns

A valid wfio_iobuf_t* instance on success; otherwise, NULL.

wfio_iobuf_clear()

WFIO_DLL int wfio_iobuf_clear	(	wfio_iobuf_t *	buf,
		int *	error
	)

Discard all data currently in current facet of this buffer.

Parameters

buf	The buffer to clear.
error	An optional error indicator.

Return nonzero on success; otherwise, zero.

wfio_iobuf_empty()

WFIO_ALWAYS_INLINE size_t wfio_iobuf_empty	(	wfio_iobuf_t *	buf,
		void *	dest,
		wfio_iobuf_sink_callback_t	cb,
		int *	error
	)

Empty this buffer into src.

This function is synonymous with wfio_iobuf_sinkbV(buf, WFIO_NPOS, dest, cb, error).

Parameters

buf	The buffer to write from.
dest	The source object to write to.
cb	The callback to invoke on writing.
error	An optional error indicator.

Returns

sz The total number of bytes written into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_ensureRead()

WFIO_INLINE int wfio_iobuf_ensureRead	(	wfio_iobuf_t *	buf,
		int *	error
	)

Ensure that buf is using the read buffer.

Parameters

buf	The buffer to modify.
error	An optional error indicator.

Returns

Nonzero iff the read buffer is now active; otherwise, zero.

wfio_iobuf_ensureWrite()

WFIO_INLINE int wfio_iobuf_ensureWrite	(	wfio_iobuf_t *	buf,
		int *	error
	)

Ensure that buf is using the write buffer.

Parameters

buf	The buffer to modify.
error	An optional error indicator.

Returns

Nonzero iff the write buffer is now active; otherwise, zero.

wfio_iobuf_fill()

WFIO_ALWAYS_INLINE size_t wfio_iobuf_fill	(	wfio_iobuf_t *	buf,
		void *	dest,
		wfio_iobuf_source_callback_t	cb,
		int *	error
	)

Fill this buffer from src.

This function is synonymous with wfio_iobuf_sourcebV(buf, WFIO_NPOS, src, cb, error).

Parameters

buf	The buffer to read into.
src	The source object to read from.
cb	The callback to invoke on reading.
error	An optional error indicator.

Returns

sz The total number of bytes read into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_flip()

WFIO_DLL int wfio_iobuf_flip	(	wfio_iobuf_t *	buf,
		int *	error
	)

Flip the buffer buf.

This does nothing for an unshared buffer; otherwise, this function swaps the current facet in use by the buffer.

Parameters

buf	The buffer to flip.
error	An optional error indicator.

Returns

Nonzero on success; otherwise, zero.

wfio_iobuf_forceReorganize()

WFIO_DLL int wfio_iobuf_forceReorganize	(	wfio_iobuf_t *	buf,
		int *	error
	)

Force reoganization of this buffer.

Parameters

buf	The buffer to reorganize.
error	An optional error indicator.

Returns

A nonzero value on success; otherwise, zero.

wfio_iobuf_free()

WFIO_DLL void wfio_iobuf_free

(

wfio_iobuf_t *

buf

)

Release the buffer buf.

Parameters

buf	The buffer to release.

wfio_iobuf_notRead()

WFIO_ALWAYS_INLINE int wfio_iobuf_notRead

(

const wfio_iobuf_t *

buf

)

Determine if the buf is shared and not using the read buffer.

Parameters

buf	The buffer to interrogate.

Returns

True iff this buffer is shared and the write buffer is active.

wfio_iobuf_notWrite()

WFIO_ALWAYS_INLINE int wfio_iobuf_notWrite

(

const wfio_iobuf_t *

buf

)

Determine if the buf is shared and not using the write buffer.

Parameters

buf	The buffer to interrogate.

Returns

True iff this buffer is shared and the read buffer is active.

wfio_iobuf_rawdata()

WFIO_INLINE void* wfio_iobuf_rawdata

(

wfio_iobuf_t *

buf

)

Obtain access to the raw data memory associated with this buffer.

Parameters

buf	The buffer to obtain the data memory from.

Returns

The memory pointing to the raw data buffer on success; otherwise, NULL.

wfio_iobuf_read()

WFIO_DLL size_t wfio_iobuf_read	(	wfio_iobuf_t *	buf,
		void *	dest,
		size_t	sz,
		size_t	elem,
		int *	error
	)

Consume elements from the buffer buf.

Parameters

buf	The buffer to read from.
dest	The data into which the buffer will read.
sz	The size of each element.
elem	The maximum number of elements to read.
error	An optional error indicator.

Returns

The number of bytes read on success; otherwise, WFIO_NPOS.

wfio_iobuf_readb()

WFIO_INLINE int wfio_iobuf_readb	(	wfio_iobuf_t *	buf,
		int *	error
	)

Consume a single from the buffer buf.

Parameters

buf	The buffer to read from.
error	An optional error indicator.

Returns

The byte read on success; otherwise, WFIO_NPOS.

wfio_iobuf_readbV()

WFIO_DLL size_t wfio_iobuf_readbV	(	wfio_iobuf_t *	buf,
		void *	dest,
		size_t	len,
		int *	error
	)

Consume bytes from the buffer buf.

Parameters

buf	The buffer to read from.
dest	The data into which the buffer will read.
len	The maximum number of elements to read.
error	An optional error indicator.

Returns

The number of bytes read on success; otherwise, WFIO_NPOS.

wfio_iobuf_remain()

WFIO_ALWAYS_INLINE size_t wfio_iobuf_remain

(

wfio_iobuf_t *

buf

)

Obtain the number of bytes left in the buffer.

Parameters

buf	The buffer to interrogate.

Returns

The number of bytes left in the buffer.

wfio_iobuf_remainElem()

WFIO_ALWAYS_INLINE size_t wfio_iobuf_remainElem	(	wfio_iobuf_t *	buf,
		size_t	sz
	)

Obtain the number of elements left in the buffer.

Parameters

buf	The buffer to interrogate.
sz	The size of each element.

Returns

The number of bytes left in the buffer.

wfio_iobuf_sink()

WFIO_DLL size_t wfio_iobuf_sink	(	wfio_iobuf_t *	buf,
		size_t	sz,
		size_t	elem,
		void *	dest,
		wfio_iobuf_sink_callback_t	cb,
		int *	error
	)

Sink new elements from buf into dest.

This function is meant to make writing directly into a device or other sink using a buffer much easier. This can be tricky because this may require multiple writes for alignment to work properly. This function invokes cb using dest for the first parameter and error for the error indicator to directly fill the specified region of the buffer.

Parameters

buf	The buffer to write from.
sz	The size of each element.
elem	The number of elements to write out.
dest	The source object to write to.
cb	The callback to invoke on writing.
error	An optional error indicator.

Returns

sz The total number of bytes written into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_sinkbV()

WFIO_DLL size_t wfio_iobuf_sinkbV	(	wfio_iobuf_t *	buf,
		size_t	len,
		void *	dest,
		wfio_iobuf_sink_callback_t	cb,
		int *	error
	)

Sink new bytes from buf into dest.

This function is synonymous with wfio_iobuf_sink(buf, 1, len, dest, cb, error).

Parameters

buf	The buffer to write from.
len	The maximum number of bytes to write.
dest	The source object to write to.
cb	The callback to invoke on writing.
error	An optional error indicator.

Returns

sz The total number of bytes written into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_source()

WFIO_DLL size_t wfio_iobuf_source	(	wfio_iobuf_t *	buf,
		size_t	sz,
		size_t	elem,
		void *	src,
		wfio_iobuf_source_callback_t	cb,
		int *	error
	)

Source new elements into buf from src.

This function is meant to make reading directly from a device or other source into a buffer much easier. This can be tricky because this may require multiple reads for alignment to work properly. This function invokes cb using for the first parameter and error for the error indicator to directly fill the specified region of the buffer.

Parameters

buf	The buffer to read into.
sz	The size of each element.
elem	The number of elements to read in.
src	The source object to read from.
cb	The callback to invoke on reading.
error	An optional error indicator.

Returns

sz The total number of bytes read into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_sourcebV()

WFIO_DLL size_t wfio_iobuf_sourcebV	(	wfio_iobuf_t *	buf,
		size_t	len,
		void *	src,
		wfio_iobuf_source_callback_t	cb,
		int *	error
	)

Source new bytes into buf from src.

This function is synonymous with wfio_iobuf_source(buf, 1, len, src, cb, error).

Parameters

buf	The buffer to read into.
len	The maximum number of bytes to read.
src	The source object to read from.
cb	The callback to invoke on reading.
error	An optional error indicator.

Returns

sz The total number of bytes read into the buffer on success; otherwise, WFIO_NPOS.

wfio_iobuf_write()

WFIO_DLL size_t wfio_iobuf_write	(	wfio_iobuf_t *	buf,
		const void *	src,
		size_t	sz,
		size_t	elem,
		int *	error
	)

Emplace bytes into the buffer buf.

Parameters

buf	The buffer to write to.
src	The data from which to populate this buffer.
sz	The size of each element.
elem	The maximum number of elements to write.
error	An optional error indicator.

Returns

The number of bytes written on success; otherwise, WFIO_NPOS.

wfio_iobuf_writeb()

WFIO_INLINE int wfio_iobuf_writeb	(	wfio_iobuf_t *	buf,
		char	c,
		int *	error
	)

Consume a single from the buffer buf.

Parameters

buf	The buffer to read from.
error	An optional error indicator.

Returns

The byte read on success; otherwise, WFIO_NPOS.

wfio_iobuf_writebV()

WFIO_DLL size_t wfio_iobuf_writebV	(	wfio_iobuf_t *	buf,
		const void *	src,
		size_t	len,
		int *	error
	)

Emplace bytes into the buffer buf.

Parameters

buf	The buffer to write to.
src	The data from which to populate this buffer.
len	The maximum number of elements to write.
error	An optional error indicator.

Returns

The number of bytes written on success; otherwise, WFIO_NPOS.