Write-buffered operations
[Socket streams]

---

Detailed Description

Write-buffered stream methods.

Typedefs
typedef void(*	peak_stream_error_callback )(peak_stream s, int error_type, void *context)
	Error callback for write-buffered streams.
Enumerations
enum	{ PEAK_STREAM_ERR_MAX_MSGBUF_EXCEEDED = -10001 }
	Possible error codes passed to your stream error callback function. More...
Functions
void	peak_stream_set_buffered (peak_stream s, int enable, size_t msg_size, size_t max_size, peak_stream_error_callback cb)
	Enable or disable buffered write mode for a specified stream.
void	peak_stream_msgbuf_get_info (peak_stream s, size_t *msg_size, size_t *max_msgs, size_t *alloc_msgs, size_t *queue_msgs, size_t *queue_size)
	Get info on current buffered write mode settings.
void	peak_stream_write_buffered (peak_stream s, const void *buffer, size_t bufsize)
	Copy and commit a buffer to the stream for writing.
void *	peak_stream_msgbuf_new (peak_stream s)
	Get a new message buffer.
void	peak_stream_msgbuf_commit (peak_stream s, void *buffer, int length)
	Commit a message buffer.
void	peak_stream_msgbuf_make (peak_stream s, const char *format,...)
	Make a formatted message buffer and commit it for writing.
void	peak_stream_msgbuf_vmake (peak_stream s, const char *format, va_list vl)
	Make a formatted message buffer and commit it for writing.

---

Typedef Documentation

typedef void(* peak_stream_error_callback)(peak_stream s, int error_type, void *context)

Error callback for write-buffered streams. Defines a pointer to your error handling callback function that will be triggered when a stream error happens. Warning: NEVER release a stream inside this callback!

---

Enumeration Type Documentation

anonymous enum

Possible error codes passed to your stream error callback function. These are currently only used with write-buffered configured streams. Enumeration values: PEAK_STREAM_ERR_MAX_MSGBUF_EXCEEDED  All allowed message buffers of a write-buffered stream have been consumed!

---

Function Documentation

void peak_stream_msgbuf_commit (  peak_stream  s, void *  buffer, int  length )

Commit a message buffer. After a message buffer (obtained with the help of peak_stream_msgbuf_new()) has been filled partially or completely, you MUST call this function to commit the message for sending. This function is O(1). Parameters: s  The stream reference. buffer  A filled buffer obtained with peak_stream_msgbuf_new(). length  Actual length of data you want to commit, you might use a value of 0 to properly cancel the allocated msgbuf, but obviously it's not something efficient to do. Returns: A pointer to a new msgbuf or NULL is max_msgs is reached internally.

void peak_stream_msgbuf_get_info (  peak_stream  s, size_t *  msg_size, size_t *  max_msgs, size_t *  alloc_msgs, size_t *  queue_msgs, size_t *  queue_size )

Get info on current buffered write mode settings. You may only call this function if the stream s is configured in write-buffered mode. msg_size and max_msgs can be configured using the peak_stream_set_buffered() function. Parameters: s  The stream reference. msg_size  If not NULL, the value pointed will contain the max size in bytes of each message buffers. max_msgs  If not NULL, the value pointed will contain the maximum number of message. alloc_msgs  If not NULL, the value pointed will contain the number of actual allocated message buffer (alloc_msgs <= max_msgs). queue_msgs  If not NULL, the value pointed will contain the current number of message buffers queued (used). Obviously you can get the free count of message buffers with (max_msgs - queue_msgs). queue_size  If not NULL, the value pointed will contain the current write queue size in bytes (also named "SendQ").

void peak_stream_msgbuf_make (  peak_stream  s, const char *  format, ...  )

Make a formatted message buffer and commit it for writing. This convenience function allows you to write a formatted string to the stream in write-buffered mode. Parameters: s  The stream reference. format  Format string.

void* peak_stream_msgbuf_new (  peak_stream  s  )

Get a new message buffer. Low-level function to get a pointer to a new msgbuf, of msg_size bytes (previously configured with peak_stream_set_buffered()). This function is usually O(1), except for the few first calls or it needs to do real allocations. You can fill it partially or completely and then you MUST call peak_stream_msgbuf_commit() to commit the message for sending. Parameters: s  The stream reference. Returns: A pointer to a new msgbuf or NULL is max_msgs is reached internally.

void peak_stream_msgbuf_vmake (  peak_stream  s, const char *  format, va_list  vl )

Make a formatted message buffer and commit it for writing. This convenience function allows you to write a formatted string to the stream in write-buffered mode. Parameters: s  The stream reference. format  Format string. vl  Arguments.

void peak_stream_set_buffered (  peak_stream  s, int  enable, size_t  msg_size, size_t  max_size, peak_stream_error_callback  cb )

Enable or disable buffered write mode for a specified stream. Parameters: s  The stream reference. enable  Enable (1) or disable (0) buffered mode ? msg_size  Size in bytes of a single message. Take care when setting this when you want to write lines: it's the maximum number of characters a line can contain when using the peak_stream_msgbuf's API. Use 0 to get an optimized value if you don't use the peak_stream_msgbuf's API. max_size  Set a limit of the total size in bytes of all messages, as you wish, depending on you needs and traffic. Also known as the SendQ's total size, but remember a few more bytes are allocated internally to implement the buffered writes. cb  A pointer to your errors handling callback function for write-buffered related errors or NULL if you don't care. But be careful, the write stream isn't reliable anymore if you don't handle write-buffered errors because messages might be dropped in secret.

void peak_stream_write_buffered (  peak_stream  s, const void *  buffer, size_t  bufsize )

Copy and commit a buffer to the stream for writing. This is the write-buffered version of peak_stream_write(). If max_msgs (previously configured with peak_stream_set_buffered()) is not reached, this function will send the whole buffer without error. If you want maximum efficiency and if it's adapted for you, please use the peak_stream_msgbuf_new() and peak_stream_msgbuf_commit() pair, as they provide zero-copy buffering. Parameters: s  The stream reference. buffer  The bytes to write. bufsize  Number of bytes to write. Returns: The number of bytes which where written or -1 if an error occured.

---