NAME

       TSIOBufferReader - traffic Server IO buffer reader API

SYNOPSIS

          #include <ts/ts.h>

       TSIOBufferReader TSIOBufferReaderAlloc(TSIOBuffer bufp)

       TSIOBufferReader TSIOBufferReaderClone(TSIOBufferReader readerp)

       void TSIOBufferReaderFree(TSIOBufferReader readerp)

       void TSIOBufferReaderConsume(TSIOBufferReader readerp, int64_t nbytes)

       TSIOBufferBlock TSIOBufferReaderStart(TSIOBufferReader readerp)

       int64_t TSIOBufferReaderAvail(TSIOBufferReader readerp)

       int64_t TSIOBufferReaderCopy(TSIOBufferReader reader, void *buf, int64_t length)

DESCRIPTION

       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() allocate a reader.
              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() duplicate a reader.
              A reader for bufp is allocated and the initial reader position is  set  to  be  the
              same as reader.

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

       TSIOBufferReaderConsume() consume data from reader.
              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() Get the first buffer block.
              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() returns the number of bytes available.
              The bytes available is the amount of data that could be read from reader.

       TSIOBufferReaderCopy() copies data from reader into buff.
              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.

SEE ALSO

       TSIOBufferCreate(3ts)

COPYRIGHT

       2023, dev@trafficserver.apache.org