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 TSIOBufferReadAvail(TSIOBufferReader readerp)

       bool TSIOBufferReaderIsAvailAtLeast(TSIOBufferReader, int64_t nbytes)

       int64_t TSIOBufferReaderRead(TSIOBufferReader reader, const void * buf, int64_t length)

       bool      TSIOBufferReaderIterate(TSIOBufferReader reader,      TSIOBufferBlockFunc* func,
       void* context)

       TSIOBufferBlockFunc
              bool (*TSIOBufferBlockFunc)(void const* data, int64_t nbytes, void* context)

              data is the data in the TSIOBufferBlock and is nbytes long. context is opaque  data
              provided  to  the  API call along with this function and passed on to the function.
              This function should return true  to  continue  iteration  or  false  to  terminate
              iteration.

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 maxium is  reached  at  which
       point it fails.

       TSIOBufferReaderAlloc() allocates a reader for the IO buffer bufp. 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()  allocates  a reader and sets its position in the buffer to be the
       same as reader.

       TSIOBufferReaderFree() de-allocates the reader. Any data referenced only by this reader is
              discarded from the buffer.

       TSIOBufferReaderConsume() advances the position of reader in its IO buffer by the
              the smaller of nbytes and the maximum available in the buffer.

       TSIOBufferReaderStart() returns the IO buffer block containing the position of reader.

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

       TSIOBufferReadAvail() returns the number of bytes which reader could consume. That is
              the number of bytes in the IO buffer starting at the current position of reader.

       TSIOBufferReaderIsAvailAtLeast() return true if the available number of bytes for
              reader  is  at  least  nbytes,  false  if  not.  This  can  be  more efficient than
              TSIOBufferReadAvail() because the latter must walk all the IO buffer blocks in  the
              IO  buffer. This function returns as soon as the return value can be determined. In
              particular a value of 1 for nbytes means  only  the  first  buffer  block  will  be
              checked.

       TSIOBufferReaderRead() reads data from reader. This first copies data from the IO
              buffer  for  reader  to  the target buffer bufp, starting at reader`s position, and
              then advances (as with :func:`TSIOBufferReaderConsume) reader`s position  past  the
              copied  data.  The amount of data read in this fashion is the smaller of the amount
              of data available in the IO buffer for :arg:`reader and  the  size  of  the  target
              buffer (length).

       TSIOBufferReaderIterate()  iterates  over  the  blocks  for reader. For each block func is
       called with with the data for the block and context. The context is an opaque type to this
       function  and  is passed unchanged to func. It is intended to be used as context for func.
       If func returns false the  iteration  terminates.  If  func  returns  true  the  block  is
       consumed. The return value for TSIOBufferReaderIterate() is the return value from the last
       call to func.

          NOTE:
              If it would be a problem for the iteration to consume the data (especially in cases
              where false might be returned) the reader can be cloned via TSIOBufferReaderClone()
              to keep the data in the IO buffer and available. If not needed the  reader  can  be
              destroyed  or  if  needed  the original reader can be destroyed and replaced by the
              clone.

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

SEE ALSO

       TSIOBufferCreate(3ts)

COPYRIGHT

       2018, dev@trafficserver.apache.org