TSIOBufferReader - traffic Server IO buffer reader API

       2025, dev@trafficserver.apache.org

9.2                                               May 22, 2025                             TSIOBUFFERREADER(3ts)

TSIOBufferReader  is  an  read  accessor  for TSIOBuffer. 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 --

       • 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.

       • Conversely  keeping  a  reader  around unused will pin the buffer data in memory. This can be useful or
         harmful.

       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.

       TSIOBufferReaderAlloc()allocateareader.
              A reader for the IO buffer bufp 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
              TSIOBufferReaderClone() to get another reader if the buffer is already in use.

       TSIOBufferReaderClone()duplicateareader.
              A reader for bufp is allocated and the initial reader position is set to be the same as reader.

       TSIOBufferReaderFree()de-allocatereader.
              This also effectively consumes (see TSIOBufferReaderConsume()) all data for reader.

       TSIOBufferReaderConsume()consumedatafromreader.
              This advances the position of reader in its IO buffer by the smaller of  nbytes  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.

       TSIOBufferReaderStart()Getthefirstbufferblock.
              This returns the TSIOBufferBlock which contains the first byte available to reader.

              NOTE:
                 The byte at the position of reader is in the block but is not necessarily the first byte of the
                 block.

       TSIOBufferReaderAvail()returnsthenumberofbytesavailable.
              The bytes available is the amount of data that could be read from reader.

       TSIOBufferReaderCopy()copiesdatafromreaderintobuff.
              This copies data from the IO buffer for reader to the target buffer bufp. The amount of data  read
              in this fashion is the smaller of the amount of data available in the IO buffer for reader and the
              size of the target buffer (length). The number of bytes copied is returned.

       NOTE:
          Destroying a TSIOBuffer will de-allocate and destroy all readers for that buffer.

       TSIOBufferReader - traffic Server IO buffer reader API

TSIOBufferCreate(3ts)

          #include <ts/ts.h>

       TSIOBufferReaderTSIOBufferReaderAlloc(TSIOBufferbufp)TSIOBufferReaderTSIOBufferReaderClone(TSIOBufferReaderreaderp)voidTSIOBufferReaderFree(TSIOBufferReaderreaderp)voidTSIOBufferReaderConsume(TSIOBufferReaderreaderp,int64_tnbytes)TSIOBufferBlockTSIOBufferReaderStart(TSIOBufferReaderreaderp)int64_tTSIOBufferReaderAvail(TSIOBufferReaderreaderp)int64_tTSIOBufferReaderCopy(TSIOBufferReaderreader,void*buf,int64_tlength)