NAME¶
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
index bytes.
TSIOBufferDestroy() destroys the IO buffer
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
length bytes from the buffer
buf
to the IO buffer
bufp and returns the number of bytes successfully
written into the IO buffer.
TSIOBufferProduce() makes
nbytes of data available for reading in
the IO buffer
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
bufp.
TSIOBufferWaterMarkSet() gets the current watermark for the IO buffer
bufp to
water_mark bytes.
SEE ALSO¶
TSAPI(3ts),
TSIOBufferReaderAlloc(3ts)
COPYRIGHT¶
2015, dev@trafficserver.apache.org