Core Functions

Macros
#define	sbufCreate(targetsz, ...)   _sbufCreate(targetsz, opt_flags(__VA_ARGS__))

Enumerations
enum	STREAM_BUFFER_OPT_FLAGS { SBUF_Locked = 0x0004 , SBUF_Wait = 0x0008 }
	Optional flags for sbufCreate() and the sbufPWrite() family. More...

Functions
StreamBuffer *	sbufAcquire (StreamBuffer *sb)
void	sbufRelease (StreamBuffer **sb)
void	sbufClose (StreamBuffer *sb)
void	sbufFinish (StreamBuffer **sb)
void	sbufError (StreamBuffer *sb)
void	sbufClearError (StreamBuffer *sb)
void	sbufSetWatermark (StreamBuffer *sb, size_t high, size_t low)
bool	sbufIsLocked (StreamBuffer *sb)
bool	sbufIsPull (StreamBuffer *sb)
bool	sbufIsPush (StreamBuffer *sb)
bool	sbufIsError (StreamBuffer *sb)
bool	sbufIsClosed (StreamBuffer *sb)
bool	sbufCMore (StreamBuffer *sb)

Detailed Description

Stream buffer lifetime, mode and state.

Macro Definition Documentation

sbufCreate

#define sbufCreate	(		targetsz,
			...
	)		_sbufCreate(targetsz, opt_flags(__VA_ARGS__))

StreamBuffer *sbufCreate(size_t targetsz, [flags])

Creates a new stream buffer with the specified target size.

The buffer will automatically grow as needed but tries to stay near targetsz. Set targetsz to 0 only when using direct push mode (no buffering needed).

Parameters

targetsz	Target buffer size in bytes (0 for direct mode)
...	(flags) Pass SBUF_Locked if the producer and consumer run on different threads

Returns

New stream buffer (must be released with sbufRelease)

Example:

StreamBuffer *sb = sbufCreate(4096);
// ... register the callback side and run the stream ...
sbufRelease(&sb);

Definition at line 275 of file streambuf.h.

Enumeration Type Documentation

STREAM_BUFFER_OPT_FLAGS

enum STREAM_BUFFER_OPT_FLAGS

Optional flags for sbufCreate() and the sbufPWrite() family.

Enumerator
SBUF_Locked	sbufCreate(): guard the buffer with a lock so the producer and the consumer may run on different threads. Without it a stream buffer must only ever be touched by one thread.
SBUF_Wait	sbufPWrite() and friends: wait for the buffer to drain when it is full instead of returning false. Requires SBUF_Locked, since the thread that has to drain the buffer cannot be the one that is waiting on it.

Definition at line 203 of file streambuf.h.

Function Documentation

sbufAcquire()

StreamBuffer * sbufAcquire

(

StreamBuffer *

sb

)

Takes another reference to a stream buffer.

Acquire one whenever you store the pointer somewhere that outlives the call you got it from.

Parameters

sb	The stream buffer

Returns

The same stream buffer

Example:

self->stream = sbufAcquire(sb);

sbufClearError()

void sbufClearError

(

StreamBuffer *

sb

)

void sbufClearError(StreamBuffer *sb)

Clears the error state so the stream can be used again.

For the driving side, once it has dealt with whatever failed. Any data still buffered is kept; call sbufCSkip() to throw away a partial record.

Parameters

sb	The stream buffer

sbufClose()

void sbufClose

(

StreamBuffer *

sb

)

Closes the stream to traffic.

Called by whichever side is driving: the producer in push mode, the consumer in pull mode. No more data will be written, but a consumer may still drain what is already buffered. The registered side gets one final callback with sz == 0, and anything still registered once that callback returns is detached, as if it had called sbufPUnregister() or sbufCUnregister() itself.

This does not release your own reference. Use sbufFinish() to close and release in one step.

Parameters

sb	The stream buffer (NULL does nothing)

sbufCMore()

bool sbufCMore

(

StreamBuffer *

sb

)

Checks whether more data may still arrive.

False once the stream has closed, once it has failed, or while no producer is attached to a pull stream. This is the test a drain loop wants:

while (sz > 0 || sbufCMore(sb)) { ... }

Parameters

sb	The stream buffer

Returns

true if it is worth asking for more data

sbufError()

void sbufError

(

StreamBuffer *

sb

)

void sbufError(StreamBuffer *sb)

Reports that something went wrong with the stream.

Reads and writes fail while the error stands, so the driving side finds out on its next call. The stream is not over: the driving side may end it, or unregister whoever failed, call sbufClearError() and attach a replacement.

This is the one function a send callback given to sbufCSend() may call on the buffer it was passed.

Parameters

sb	The stream buffer

sbufFinish()

void sbufFinish

(

StreamBuffer **

sb

)

Closes the stream and releases your reference to it.

The usual way to be finished with a buffer, and the same thing as sbufClose() followed by sbufRelease(). Sets the pointer to NULL. Does nothing if it is already NULL.

Only the driving side closes a stream, so a registered party that is merely done with its role calls sbufPUnregister() or sbufCUnregister() instead.

Parameters

sb	Pointer to stream buffer pointer

Example:

sbufFinish(&sb);

sbufIsClosed()

bool sbufIsClosed ( StreamBuffer *  sb )

inline

bool sbufIsClosed(StreamBuffer *sb)

Checks whether the stream is closed.

Data already buffered may still be read; this only says that no more is coming.

Parameters

sb	The stream buffer

Returns

true if sbufClose() has been called

Definition at line 422 of file streambuf.h.

sbufIsError()

bool sbufIsError ( StreamBuffer *  sb )

inline

bool sbufIsError(StreamBuffer *sb)

Checks if the stream buffer is in an error state.

Parameters

sb	The stream buffer

Returns

true if in error state

Definition at line 409 of file streambuf.h.

sbufIsLocked()

bool sbufIsLocked ( StreamBuffer *  sb )

inline

bool sbufIsLocked(StreamBuffer *sb)

Checks whether the buffer was created with SBUF_Locked.

Parameters

sb	The stream buffer

Returns

true if the buffer may be used from more than one thread

Definition at line 376 of file streambuf.h.

sbufIsPull()

bool sbufIsPull ( StreamBuffer *  sb )

inline

bool sbufIsPull(StreamBuffer *sb)

Checks if the stream buffer is in pull mode.

Parameters

sb	The stream buffer

Returns

true if in pull mode

Definition at line 387 of file streambuf.h.

sbufIsPush()

bool sbufIsPush ( StreamBuffer *  sb )

inline

bool sbufIsPush(StreamBuffer *sb)

Checks if the stream buffer is in push mode.

Parameters

sb	The stream buffer

Returns

true if in push mode

Definition at line 398 of file streambuf.h.

sbufRelease()

void sbufRelease

(

StreamBuffer **

sb

)

void sbufRelease(StreamBuffer **sb)

Releases a reference to a stream buffer.

Decrements the reference count and destroys the buffer when it reaches zero. Sets the pointer to NULL after release.

Parameters

sb	Pointer to stream buffer pointer

sbufSetWatermark()

void sbufSetWatermark	(	StreamBuffer *	sb,
		size_t	high,
		size_t	low
	)

Sets the flow control watermarks.

Once the amount of buffered data reaches high, the producer is held until the consumer drains it back down to low. Held means either waiting inside sbufPWrite() or being refused by it, depending on whether the write passed SBUF_Wait. Both marks default to 0, which lets the buffer grow without limit.

Parameters

sb	The stream buffer
high	Amount of buffered data that holds the producer (0 turns flow control off)
low	Amount to drain back down to before releasing it (0 uses half of high)

Example:

sbufSetWatermark(sb, 65536, 16384);