.\" Man page generated from reStructuredText.
.
.TH "TSIOBUFFERREADER" "3ts" "Mar 08, 2019" "7.1" "Apache Traffic Server"
.SH NAME
TSIOBufferReader \- traffic Server IO buffer reader API
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SYNOPSIS
.sp
\fI#include <ts/ts.h>\fP
.INDENT 0.0
.TP
.B TSIOBufferReader TSIOBufferReaderAlloc(TSIOBuffer\fI\ bufp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B TSIOBufferReader TSIOBufferReaderClone(TSIOBufferReader\fI\ readerp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferReaderFree(TSIOBufferReader\fI\ readerp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferReaderConsume(TSIOBufferReader\fI\ readerp\fP, int64_t\fI\ nbytes\fP)
.UNINDENT
.INDENT 0.0
.TP
.B TSIOBufferBlock TSIOBufferReaderStart(TSIOBufferReader\fI\ readerp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferReadAvail(TSIOBufferReader\fI\ readerp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B bool TSIOBufferReaderIsAvailAtLeast(TSIOBufferReader, int64_t\fI\ nbytes\fP)
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferReaderRead(TSIOBufferReader\fI\ reader\fP, const void *\fI\ buf\fP, int64_t\fI\ length\fP)
.UNINDENT
.INDENT 0.0
.TP
.B bool TSIOBufferReaderIterate(TSIOBufferReader\fI\ reader\fP, \fI\%TSIOBufferBlockFunc\fP*\fI\ func\fP, void*\fI\ context\fP)
.UNINDENT
.INDENT 0.0
.TP
.B TSIOBufferBlockFunc
\fBbool (*TSIOBufferBlockFunc)(void const* data, int64_t nbytes, void* context)\fP
.sp
\fIdata\fP is the data in the \fBTSIOBufferBlock\fP and is \fInbytes\fP long. \fIcontext\fP is
opaque data provided to the API call along with this function and passed on to the function. This
function should return \fBtrue\fP to continue iteration or \fBfalse\fP to terminate iteration.
.UNINDENT
.SH DESCRIPTION
.sp
\fBTSIOBufferReader\fP is an read accessor for \fBTSIOBuffer\fP\&. 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 \-\-
.INDENT 0.0
.IP \(bu 2
.INDENT 2.0
.TP
.B 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.
.UNINDENT
.IP \(bu 2
Conversely keeping a reader around unused will pin the buffer data in memory. This can be useful or harmful.
.UNINDENT
.sp
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 maxium is reached at which point it fails.
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReaderAlloc()\fP allocates a reader for the IO buffer \fIbufp\fP\&. This should only be
called on a newly allocated buffer. If not the location of the reader in the buffer will be
indeterminate. Use \fI\%TSIOBufferReaderClone()\fP to get another reader if the buffer is
already in use.
.UNINDENT
.sp
\fI\%TSIOBufferReaderClone()\fP allocates a reader and sets its position in the buffer to be the same as \fIreader\fP\&.
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReaderFree()\fP de\-allocates the reader. Any data referenced only by this reader is
discarded from the buffer.
.TP
.B \fI\%TSIOBufferReaderConsume()\fP advances the position of \fIreader\fP in its IO buffer by the
the smaller of \fInbytes\fP and the maximum available in the buffer.
.UNINDENT
.sp
\fI\%TSIOBufferReaderStart()\fP returns the IO buffer block containing the position of
\fIreader\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The byte at the position of \fIreader\fP is in the block but is not necessarily the first byte of the block.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReadAvail()\fP returns the number of bytes which \fIreader\fP could consume. That is
the number of bytes in the IO buffer starting at the current position of \fIreader\fP\&.
.TP
.B \fI\%TSIOBufferReaderIsAvailAtLeast()\fP return \fBtrue\fP if the available number of bytes for
\fIreader\fP is at least \fInbytes\fP, \fBfalse\fP if not. This can be more efficient than
\fI\%TSIOBufferReadAvail()\fP 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 \fB1\fP for \fInbytes\fP means only the first buffer block will be checked.
.TP
.B \fI\%TSIOBufferReaderRead()\fP reads data from \fIreader\fP\&. This first copies data from the IO
buffer for \fIreader\fP to the target buffer \fIbufp\fP, starting at \fIreader\(gas
position, and then advances (as with :func:\(gaTSIOBufferReaderConsume\fP) \fIreader\(gas
position past the copied data. The amount of data read in this fashion is the smaller of the
amount of data available in the IO buffer for :arg:\(gareader\fP and the size of the target buffer
(\fIlength\fP).
.UNINDENT
.sp
\fI\%TSIOBufferReaderIterate()\fP iterates over the blocks for \fIreader\fP\&. For each block
\fIfunc\fP is called with with the data for the block and \fIcontext\fP\&. The \fIcontext\fP is an
opaque type to this function and is passed unchanged to \fIfunc\fP\&. It is intended to be used as
context for \fIfunc\fP\&. If \fIfunc\fP returns \fBfalse\fP the iteration terminates. If \fIfunc\fP
returns true the block is consumed. The return value for \fI\%TSIOBufferReaderIterate()\fP is the
return value from the last call to \fIfunc\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
If it would be a problem for the iteration to consume the data (especially in cases where
\fBfalse\fP might be returned) the reader can be cloned via \fI\%TSIOBufferReaderClone()\fP 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.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Destroying a \fBTSIOBuffer\fP will de\-allocate and destroy all readers for that buffer.
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBTSIOBufferCreate(3ts)\fP
.SH COPYRIGHT
2019, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.