TSIOBufferCreate

Traffic Server IO buffer API.

Synopsis

#include <ts/ts.h>

TSIOBuffer TSIOBufferCreate(void)

TSIOBuffer TSIOBufferSizedCreate(TSIOBufferSizeIndex index)

void TSIOBufferDestroy(TSIOBuffer bufp)

int64_t TSIOBufferWrite(TSIOBuffer bufp, const void * buf, int64_t length)

void TSIOBufferProduce(TSIOBuffer bufp, int64_t nbytes)

int64_t TSIOBufferWaterMarkGet(TSIOBuffer bufp)

void TSIOBufferWaterMarkSet(TSIOBuffer bufp, int64_t water_mark)

Description

The TSIOBuffer data structure is the building block of the TSVConn abstraction. An IO buffer is composed of a list of buffer blocks which are reference counted so that they can reside in multiple buffers at the same time. This makes it extremely efficient to copy data from one IO buffer to another using TSIOBufferCopy() since Traffic Server only needs to copy pointers and adjust reference counts appropriately and not actually copy any data. However, applications should still strive to ensure data blocks are a reasonable size.

The IO buffer abstraction provides for a single writer and multiple readers. In order for the readers to have no knowledge of each other, they manipulate IO buffers through the TSIOBufferReader data structure. Since only a single writer is allowed, there is no corresponding TSIOBufferWriter data structure. The writer simply modifies the IO buffer directly.

TSIOBufferCreate() creates an empty TSIOBuffer.

TSIOBufferSizedCreate() creates an empty TSIOBuffer with an initial capacity of :arg:`index` bytes.

TSIOBufferDestroy() destroys the IO buffer :arg:`bufp`. Since multiple IO buffers can share data, this does not necessarily free all of the data associated with the IO buffer but simply decrements the appropriate reference counts.

TSIOBufferWrite() appends :arg:`length` bytes from the buffer :arg:`buf` to the IO buffer :arg:`bufp` and returns the number of bytes successfully written into the IO buffer.

TSIOBufferProduce() makes :arg:`nbytes` of data available for reading in the IO buffer :arg:`bufp`. A common pattern for writing to an IO buffer is to copy data into a buffer block and then call INKIOBufferProduce to make the new data visible to any readers.

The watermark of an TSIOBuffer is the minimum number of bytes of data that have to be in the buffer before calling back any continuation that has initiated a read operation on this buffer. As a writer feeds data into the TSIOBuffer, no readers are called back until the amount of data reaches the watermark. Setting a watermark can improve performance because it avoids frequent callbacks to read small amounts of data. TSIOBufferWaterMarkGet() gets the current watermark for the IO buffer :arg:`bufp`.

TSIOBufferWaterMarkSet() gets the current watermark for the IO buffer :arg:`bufp` to :arg:`water_mark` bytes.

See Also

TSAPI(3ts), TSIOBufferReaderAlloc(3ts)