Producer Functions

Macros
#define	sbufPWrite(sb, buf, sz, ...)   _sbufPWrite(sb, buf, sz, opt_flags(__VA_ARGS__))
#define	sbufPWriteStr(sb, str, ...)   _sbufPWriteStr(sb, str, opt_flags(__VA_ARGS__))
#define	sbufPWriteLine(sb, str, ...)   _sbufPWriteLine(sb, str, opt_flags(__VA_ARGS__))
#define	sbufPWriteEOL(sb, ...)   _sbufPWriteEOL(sb, opt_flags(__VA_ARGS__))

Functions
bool	sbufPRegisterPull (StreamBuffer *sb, closure ppull)
void	sbufPUnregister (StreamBuffer *sb)
bool	sbufPAttached (StreamBuffer *sb)
void	sbufPSetResume (StreamBuffer *sb, closure resume)
bool	sbufPIsHeld (StreamBuffer *sb)
size_t	sbufPAvail (StreamBuffer *sb)
bool	sbufPFlush (StreamBuffer *sb)

Detailed Description

Functions for the producer side of stream buffer operations.

Macro Definition Documentation

sbufPWrite

#define sbufPWrite	(		sb,
			buf,
			sz,
			...
	)		_sbufPWrite(sb, buf, sz, opt_flags(__VA_ARGS__))

bool sbufPWrite(StreamBuffer *sb, const uint8 *buf, size_t sz, [flags])

Writes data to the buffer.

This always succeeds unless the stream has closed or failed, the buffer is full, or the system is out of memory. The buffer grows past its target size rather than short-writing.

With no consumer attached the data simply accumulates, and the next consumer to register is handed all of it.

Parameters

sb	The stream buffer
buf	Data to write
sz	Number of bytes to write
...	(flags) Pass SBUF_Wait to wait at the watermark instead of being refused

Returns

true on success, false if the stream closed or failed, or the buffer is full

Definition at line 541 of file streambuf.h.

sbufPWriteEOL

#define sbufPWriteEOL	(		sb,
			...
	)		_sbufPWriteEOL(sb, opt_flags(__VA_ARGS__))

bool sbufPWriteEOL(StreamBuffer *sb, [flags])

Writes a system-dependent line ending to the buffer.

Uses \r\n on Windows, \n on Unix systems.

Parameters

sb	The stream buffer
...	(flags) Pass SBUF_Wait to wait at the watermark instead of being refused

Returns

true on success, false on error

Definition at line 583 of file streambuf.h.

sbufPWriteLine

#define sbufPWriteLine	(		sb,
			str,
			...
	)		_sbufPWriteLine(sb, str, opt_flags(__VA_ARGS__))

bool sbufPWriteLine(StreamBuffer *sb, strref str, [flags])

Writes a string followed by a system-dependent line ending to the buffer.

Uses \r\n on Windows, \n on Unix systems.

Parameters

sb	The stream buffer
str	String to write
...	(flags) Pass SBUF_Wait to wait at the watermark instead of being refused

Returns

true on success, false on error

Definition at line 569 of file streambuf.h.

sbufPWriteStr

#define sbufPWriteStr	(		sb,
			str,
			...
	)		_sbufPWriteStr(sb, str, opt_flags(__VA_ARGS__))

bool sbufPWriteStr(StreamBuffer *sb, strref str, [flags])

Writes a string to the buffer.

Parameters

sb	The stream buffer
str	String to write
...	(flags) Pass SBUF_Wait to wait at the watermark instead of being refused

Returns

true on success, false on error

Definition at line 554 of file streambuf.h.

Function Documentation

sbufPAttached()

bool sbufPAttached

(

StreamBuffer *

sb

)

Checks whether a producer callback is currently attached.

Only pull streams have one; this is always false in push mode, where the producer drives.

Parameters

sb	The stream buffer

Returns

true if a pull producer is registered

sbufPAvail()

size_t sbufPAvail

(

StreamBuffer *

sb

)

size_t sbufPAvail(StreamBuffer *sb)

Returns the available space for writing to the buffer.

Parameters

sb	The stream buffer

Returns

Number of bytes available for writing

sbufPFlush()

bool sbufPFlush

(

StreamBuffer *

sb

)

Hands the consumer everything written so far and reports whether it took all of it.

Use this mid-stream, whenever the producer needs to know its bytes have landed – at the end of a frame, or before swapping the consumer out. It says nothing about the stream being over.

On an unlocked buffer this notifies the consumer and returns right away. On a locked buffer it also waits for the consumer's thread to finish draining.

Not valid in pull mode, where the buffer only fills on demand. Direct push mode never buffers, so there is nothing to catch up on and this always succeeds. Must not be called from inside a stream buffer callback.

Parameters

sb	The stream buffer

Returns

true if the buffer is now empty, false if the consumer left data behind or the stream closed or failed while waiting

sbufPIsHeld()

bool sbufPIsHeld

(

StreamBuffer *

sb

)

Checks whether the producer is currently held at the high watermark.

Use this to tell why sbufPWrite() returned false: true here means the buffer is full and a resume callback is coming, false means the stream closed or failed.

Parameters

sb	The stream buffer

Returns

true if the buffer is full and writes are being refused

sbufPRegisterPull()

bool sbufPRegisterPull	(	StreamBuffer *	sb,
		closure	ppull
	)

Registers a producer, putting the buffer in pull mode.

The consumer drives from here on: every sbufCRead() calls the producer to fill the buffer. Registration takes its own reference to the buffer and gives it back on unregister, so keep your own as well.

Takes ownership of the closure whether or not registration succeeds. It is destroyed when the producer is unregistered, or right away if registration fails.

Parameters

sb	The stream buffer
ppull	Closure created with closureCreateAs(sbufPullCB, ...)

Returns

true on success, false if a producer is already attached, the stream closed, or the buffer is already in push mode

Example:

sbufPRegisterPull(sb, closureCreateAs(sbufPullCB, readChunk, stvar(object, file)));

sbufPSetResume()

void sbufPSetResume	(	StreamBuffer *	sb,
		closure	resume
	)

Sets the closure that tells the producer it may write again.

Only useful for a producer that does not pass SBUF_Wait. When sbufPWrite() refuses a write because the buffer is full, this closure is called once the consumer has drained it back to the low mark.

Takes ownership of the closure. Any closure set earlier is destroyed, once it is no longer running. Unregistering the producer removes it too.

Parameters

sb	The stream buffer
resume	Closure created with closureCreateAs(sbufResumeCB, ...), or NULL to remove

Example:

sbufPSetResume(sb, closureCreateAs(sbufResumeCB, onResume, stvar(ptr, self)));

sbufPUnregister()

void sbufPUnregister

(

StreamBuffer *

sb

)

Detaches the producer.

Empties the producer slot, destroys its closure and gives back the reference the registration took. The stream is not closed: another producer may register, and until one does a consumer gets short reads. A pull producer that has run out of data calls this on itself.

Safe to call from inside the producer's own callback. Does nothing if no producer is attached.

Parameters

sb	The stream buffer