.. oe:namespace:: OESystem



.. _OESystem_OEThreadedDots:

.. oe:class:: OEThreadedDots

   .. oe:api::


      class OEThreadedDots

   This class provides a threadsafe version of
   :ref:`OEDots <OESystem_OEDots>`. Multiple threads can call
   :oe:meth:`OESystem::OEThreadedDots::Update` to update the progress
   in an efficient manner in a thread-safe way. This class will create
   an internal operating system thread to handle output to
   :oe:const:`OEPlatform::OEPlatform::oeerr`. The complete progress is
   not guaranteed to be output to the terminal until
   :oe:meth:`OESystem::OEThreadedDots::Total` is called.

   .. warning::

      It is an error to call
      :oe:meth:`OESystem::OEThreadedDots::Update` after calling
      :oe:meth:`OESystem::OEThreadedDots::Total`. The object is
      essentially shut down and new one should be created.

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEThreadedDots(unsigned int bigstep, unsigned int smallstep,
                           const char* objectname = "")

      .. oe:language:: python

         .. oe:api:: python

            OEThreadedDots(bigstep: int, smallstep: int, objectname: str = "") -> OEThreadedDots

      Controls how the following output gets updated::

         .......... 10000 things processed.
         .......... 20000 things processed.
         .......... 30000 things processed.
         .......... 40000 things processed.
         .......... 50000 things processed.
         .......... 60000 things processed.
         .......... 70000 things processed.
         .......... 80000 things processed.

      *bigstep*

        The number of elements before a new line is generated. The
        above example is a ``bigstep`` of ``10000``.

      *smallstep*

        The number of elements before a single new dot, ``.``, is
        printed.  The above example is a ``smallstep`` of ``1000``. Or
        10 dots per line.

      *objectname*

        A description of what is being processed. In the above
        example, this is "things".

   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEThreadedDots & operator=(const OEThreadedDots &)

      Assignment operator.

   

   .. oe:method:: Total

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Total()

      .. oe:language:: python

         .. oe:api:: python

            Total() -> None


      Prints a final summary line like the following::

         Total: 80000 things processed.

      .. note::

         Calling this method waits for all information to flush to the
         IO thread and then terminates and joins that thread. So this
         function is effectively a blocking call on those
         operations. But the operations are typically very cheap, so
         the blocking nature is not noticeable.

   .. oe:method:: Update

      .. oe:language:: c++ java csharp

         .. oe:api::

            void Update(unsigned int step = 1)

      .. oe:language:: python

         .. oe:api:: python

            Update(step: int = 1) -> None

      Update the progress with the number of elements specified by
      ``step``. The default is ``1`` element, but any number can be
      specified. However, ``0`` is not a valid step size and will
      throw an error.

      .. note::

         For :ref:`OEThreadedDots <OESystem_OEThreadedDots>`, this method is
         thread-safe to call from multiple threads even though it is a
         non-const method.
