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

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                             TSIOBUFFERCREATE(3ts)