.. include:: ../../toolkit-substitutions

.. oe:namespace:: OESystem

.. meta::
   :keywords: OEProtectedBuffer, ProtectedBuffer

.. attention::

   |CPPONLY|


.. _OESystem_OEProtectedBuffer:

.. oe:class:: OEProtectedBuffer

   .. oe:api::


      template<class BUFFER>
      class OEProtectedBuffer

   Thread-safe first-in-first-out (FIFO) queue that can have multiple
   producers and consumers. Meant to wrap around either a
   :ref:`OEBoundedBuffer <OESystem_OEBoundedBuffer>` or
   :ref:`OEUnboundedBuffer <OESystem_OEUnboundedBuffer>` object to provide thread-safe
   access to those buffers. The :ref:`OEBoundedBuffer <OESystem_OEBoundedBuffer>`
   queue should be used to control memory consumption, as the
   :oe:meth:`OESystem::OEProtectedBuffer::Put` operation will block,
   allowing the queue to empty first. The
   :ref:`OEUnboundedBuffer <OESystem_OEUnboundedBuffer>` queue will continue to
   consume memory with every
   :oe:meth:`OESystem::OEProtectedBuffer::Put` operation.

   .. oe:method:: Constructors

      .. oe:api::

         OEProtectedBuffer(oesize_t maxsize)
         OEProtectedBuffer(oesize_t maxsize, oesize_t threshold)

      Constructs a new ``BUFFER``, passing ``maxsize`` to the child
      buffer implementation. The ``threshold`` argument is a
      performance tuning parameter that determines how often
      :oe:meth:`OEPlatform::OECondition::Broadcast` is
      called. Broadcasting to other queue users too often can have
      negative performance implications as threads can be woken when
      there is not enough work in the queue to fill up their time
      quantum. Too infrequently means threads are left idle too long
      before being awoken with new to perform. The default
      ``threshold`` is half of ``maxsize``.

   .. oe:method:: Get

      .. oe:api::

         value_type Get()

      Return the next item from the queue in a thread-safe manner.

   .. oe:method:: Null

      .. oe:api::

         value_type Null()

      The value used to signal termination to the queue. Calling
      :oe:meth:`OESystem::OEProtectedBuffer::Put` with the value
      returned by the ``Null`` method signals that the queue is 'done'
      and should not accept anymore data. Subsequent
      :oe:meth:`OESystem::OEProtectedBuffer::Put` operations will fail
      and return
      ``false``. :oe:meth:`OESystem::OEProtectedBuffer::Get` will
      continue to return data until the queue is empty, and then start
      returning the result of the ``Null`` method as well. Note, this
      method returns the default constructed value for the
      ``value_type`` being stored in the queue, this is typically
      ``0`` or ``NULL`` for integral or pointer types respectively.

   .. oe:method:: Peek

      .. oe:api::

         value_type Peek()

      Returns the item that will be returned by the next call to
      :oe:meth:`OESystem::OEProtectedBuffer::Get`, but does not remove
      it from the buffer.

      .. warning::

         The above is not guaranteed if there are multiple consumers,
         i.e., other threads calling
         :oe:meth:`OESystem::OEProtectedBuffer::Get` interleaved with
         the thread calling
         :oe:meth:`OESystem::OEProtectedBuffer::Peek`.

   .. oe:method:: Put

      .. oe:api::

         bool Put(value_type obj)

      Place an item into the queue in a thread-safe manner.
