.\" Man page generated from reStructuredText.
.
.TH "TSIOBUFFERCREATE" "3ts" "Mar 08, 2019" "7.1" "Apache Traffic Server"
.SH NAME
TSIOBufferCreate \- traffic Server IO buffer 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 TSIOBuffer TSIOBufferCreate(void)
.UNINDENT
.INDENT 0.0
.TP
.B TSIOBuffer TSIOBufferSizedCreate(TSIOBufferSizeIndex\fI\ index\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferDestroy(TSIOBuffer\fI\ bufp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferWrite(TSIOBuffer\fI\ bufp\fP, const void *\fI\ buf\fP, int64_t\fI\ length\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferProduce(TSIOBuffer\fI\ bufp\fP, int64_t\fI\ nbytes\fP)
.UNINDENT
.INDENT 0.0
.TP
.B int64_t TSIOBufferWaterMarkGet(TSIOBuffer\fI\ bufp\fP)
.UNINDENT
.INDENT 0.0
.TP
.B void TSIOBufferWaterMarkSet(TSIOBuffer\fI\ bufp\fP, int64_t\fI\ water_mark\fP)
.UNINDENT
.SH DESCRIPTION
.sp
The \fBTSIOBuffer\fP data structure is the building block of the
\fBTSVConn\fP
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 \fBTSIOBufferCopy()\fP 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.
.sp
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 \fBTSIOBufferReader\fP
data structure. Since only a single writer is allowed, there is no
corresponding \fITSIOBufferWriter\fP data structure. The writer
simply modifies the IO buffer directly.
.sp
\fI\%TSIOBufferCreate()\fP creates an empty \fBTSIOBuffer\fP\&.
.sp
\fI\%TSIOBufferSizedCreate()\fP creates an empty \fBTSIOBuffer\fP
with an initial capacity of \fIindex\fP bytes.
.sp
\fI\%TSIOBufferDestroy()\fP destroys the IO buffer \fIbufp\fP\&. 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.
.sp
\fI\%TSIOBufferWrite()\fP appends \fIlength\fP bytes from the buffer \fIbuf\fP to the IO
buffer \fIbufp\fP and returns the number of bytes successfully written into the
IO buffer.
.sp
\fI\%TSIOBufferProduce()\fP makes \fInbytes\fP of data available for reading in the IO
buffer \fIbufp\fP\&. 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.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
The above references an old API function: INKIOBufferProduce and needs to
be fixed. I don\(aqt see a TSIOBufferProduce function that would be its
obvious replacement from the Ink\->TS rename.
.UNINDENT
.UNINDENT
.sp
The watermark of an \fBTSIOBuffer\fP 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 \fBTSIOBuffer\fP, 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.
\fI\%TSIOBufferWaterMarkGet()\fP gets the current watermark for the IO buffer
\fIbufp\fP\&.
.sp
\fI\%TSIOBufferWaterMarkSet()\fP gets the current watermark for the IO buffer
\fIbufp\fP to \fIwater_mark\fP bytes.
.SH SEE ALSO
.sp
\fBTSAPI(3ts)\fP,
\fBTSIOBufferReaderAlloc(3ts)\fP
.SH COPYRIGHT
2019, dev@trafficserver.apache.org
.\" Generated by docutils manpage writer.
.