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

7.1                                               Feb 16, 2018                             TSIOBUFFERREADER(3ts)