TSIOBufferReader

Traffic Server IO buffer reader API.

Synopsis

#include <ts/ts.h>

TSIOBufferReader TSIOBufferReaderAlloc(TSIOBuffer bufp)
TSIOBufferReader TSIOBufferReaderClone(TSIOBufferReader readerp)
void TSIOBufferReaderFree(TSIOBufferReader readerp)
void TSIOBufferReaderConsume(TSIOBufferReader readerp, int64_t nbytes)
TSIOBufferBlock TSIOBufferReaderStart(TSIOBufferReader readerp)
int64_t TSIOBufferReaderAvail(TSIOBufferReader readerp)
bool TSIOBufferReaderIsAvailAtLeast(TSIOBufferReader, int64_t nbytes)
int64_t TSIOBufferReaderCopy(TSIOBufferReader reader, void * buf, int64_t length)
bool TSIOBufferReaderIterate(TSIOBufferReader reader, TSIOBufferBlockFunc* func, void* context)
TSIOBufferBlockFunc

bool (*TSIOBufferBlockFunc)(void const* data, int64_t nbytes, void* context)

data is the data in the TSIOBufferBlock and is nbytes long. context is opaque data provided to the API call along with this function and passed on to the function. This function should return true to continue iteration or false to terminate iteration.

Description

TSIOBufferReader is an read accessor for TSIOBuffer. It represents a location in the contents of the buffer. A buffer can have multiple readers and each reader consumes data in the buffer independently. Data which for which there are no readers is discarded from the buffer. This has two very important consequences –

  • Data for which there are no readers and no writer will be discarded. In effect this means without any readers only the current write buffer block will be maintained, older buffer blocks will disappear.

  • Conversely keeping a reader around unused will pin the buffer data in memory. This can be useful or harmful.

A buffer has a fixed amount of possible readers (currently 5) which is determined at compile time. Reader allocation is fast and cheap until this maximum is reached at which point it fails.

TSIOBufferReaderAlloc() allocate a reader.

A reader for the IO buffer bufp is created and returned. This should only be called on a newly allocated buffer. If not the location of the reader in the buffer will be indeterminate. Use TSIOBufferReaderClone() to get another reader if the buffer is already in use.

TSIOBufferReaderClone() duplicate a reader.

A reader for bufp is allocated and the initial reader position is set to be the same as reader.

TSIOBufferReaderFree() de-allocate reader.

This also effectively consumes (see TSIOBufferReaderConsume()) all data for reader.

TSIOBufferReaderConsume() consume data from reader.

This advances the position of reader in its IO buffer by the the smaller of nbytes and the maximum available in the buffer. This is required to release the buffer memory - when data has been consumed by all readers, it is discarded.

TSIOBufferReaderStart() Get the first buffer block.

This returns the TSIOBufferBlock which contains the first byte available to reader.

Note

The byte at the position of reader is in the block but is not necessarily the first byte of the block.

TSIOBufferReaderAvail() returns the number of bytes available.

The bytes available is the amount of data that could be read from reader.

TSIOBufferReaderIsAvailAtLeast() - check amount of data available.

This function returns true if the available number of bytes for reader is at least nbytes, false if not. This can be much more efficient than TSIOBufferReaderAvail() because the latter must walk all the IO buffer blocks in the IO buffer. This function returns as soon as the return value can be determined. In particular a value of 1 for nbytes means only the first buffer block will be checked making the call very fast.

TSIOBufferReaderCopy() copies data from reader into buff.

This copies data from the IO buffer for reader to the target buffer bufp. The amount of data read in this fashion is the smaller of the amount of data available in the IO buffer for reader and the size of the target buffer (length). The number of bytes copied is returned.

TSIOBufferReaderIterate() iterate over the blocks for reader.

For each block func is called with with the data for the block and context. The context is an opaque type to this function and is passed unchanged to func. It is intended to be used as context for func. If func returns false the iteration terminates. If func returns true the block is consumed. The return value for TSIOBufferReaderIterate() is the return value from the last call to func.

Note

If it would be a problem for the iteration to consume the data (especially in cases where false might be returned) the reader can be cloned via TSIOBufferReaderClone() to keep the data in the IO buffer and available. If not needed the reader can be destroyed or if needed the original reader can be destroyed and replaced by the clone.

Note

Destroying a TSIOBuffer will de-allocate and destroy all readers for that buffer.

See also

TSIOBufferCreate(3ts)