.\" Man page generated from reStructuredText.
.
.
.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
..
.TH "TSIOBUFFERREADER" "3ts" "Apr 16, 2024" "9.2" "Apache Traffic Server"
.SH NAME
TSIOBufferReader \- traffic Server IO buffer reader API
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
#include <ts/ts.h>
.EE
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReader\fP TSIOBufferReaderAlloc(\fI\%TSIOBuffer\fP bufp) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReader\fP TSIOBufferReaderClone(\fI\%TSIOBufferReader\fP readerp) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferReaderFree(\fI\%TSIOBufferReader\fP readerp) 
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferReaderConsume(\fI\%TSIOBufferReader\fP readerp, int64_t nbytes) 
.UNINDENT
.INDENT 0.0
.TP
.B \fI\%TSIOBufferBlock\fP TSIOBufferReaderStart(\fI\%TSIOBufferReader\fP readerp) 
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferReaderAvail(\fI\%TSIOBufferReader\fP readerp) 
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferReaderCopy(\fI\%TSIOBufferReader\fP reader, void *buf, int64_t length) 
.UNINDENT
.SH DESCRIPTION
.sp
\fI\%TSIOBufferReader\fP is an read accessor for \fI\%TSIOBuffer\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
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.
.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 maximum is reached at which point it fails.
.INDENT 0.0
.TP
.B \fI\%TSIOBufferReaderAlloc()\fP allocate a reader.
A reader for the IO buffer \fIbufp\fP 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 \fI\%TSIOBufferReaderClone()\fP to get another reader if the buffer is already in use.
.TP
.B \fI\%TSIOBufferReaderClone()\fP duplicate a reader.
A reader for \fIbufp\fP is allocated and the initial reader position is set to be the same as
\fIreader\fP\&.
.TP
.B \fI\%TSIOBufferReaderFree()\fP de\-allocate \fIreader\fP\&.
This also effectively consumes (see \fI\%TSIOBufferReaderConsume()\fP) all data for \fIreader\fP\&.
.TP
.B \fI\%TSIOBufferReaderConsume()\fP consume data from \fIreader\fP\&.
This advances the position of \fIreader\fP in its IO buffer by the smaller of \fInbytes\fP
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.
.TP
.B \fI\%TSIOBufferReaderStart()\fP Get the first buffer block.
This returns the \fI\%TSIOBufferBlock\fP which contains the first byte available to \fIreader\fP\&.
.sp
\fBNOTE:\fP
.INDENT 7.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
.TP
.B \fI\%TSIOBufferReaderAvail()\fP returns the number of bytes available.
The bytes available is the amount of data that could be read from \fIreader\fP\&.
.TP
.B \fI\%TSIOBufferReaderCopy()\fP copies data from \fIreader\fP into \fIbuff\fP\&.
This copies data from the IO buffer for \fIreader\fP to the target buffer \fIbufp\fP\&. The
amount of data read in this fashion is the smaller of the amount of data available in the IO
buffer for \fIreader\fP and the size of the target buffer (\fIlength\fP). The number of bytes
copied is returned.
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
Destroying a \fI\%TSIOBuffer\fP will de\-allocate and destroy all readers for that buffer.
.UNINDENT
.UNINDENT
.SH SEE ALSO
.sp
\fBTSIOBufferCreate(3ts)\fP
.SH COPYRIGHT
2024, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.