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.

       NOTE:
          The above references an old API function: INKIOBufferProduce and needs to be  fixed.  I
          don't  see  a TSIOBufferProduce function that would be its obvious replacement from the
          Ink->TS rename.

       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

       2023, dev@trafficserver.apache.org