.. oe:namespace:: OEFastROCS



.. meta::
   :keywords: OEDBTracer, DBTracer


.. _OEFastROCS_OEDBTracer:

.. oe:class:: OEDBTracer

   .. oe:api::

      class OEDBTracer : public OEDBTracerBase

   A thread-safe implementation of :ref:`OEDBTracerBase <OEFastROCS_OEDBTracerBase>`
   meant for tracking the progress of a
   :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` query.

   The following methods are publicly inherited from :ref:`OEDBTracerBase <OEFastROCS_OEDBTracerBase>`:

   ========================================================= ========================================================= =========================================================
   :oe:meth:`SetTotal<OEFastROCS::OEDBTracerBase::SetTotal>` :oe:meth:`Update<OEFastROCS::OEDBTracerBase::Update>`
   ========================================================= ========================================================= =========================================================

   .. oe:method:: Constructors

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

         .. oe:api::

            OEDBTracer(size_t numBins = 0)

      .. oe:language:: python

         .. oe:api:: python

            OEDBTracer(numBins: int = 0) -> OEDBTracer

      Construct a new thread-safe ``OEDBTracer`` object and initialize
      the internal synchronization primitives that are required.

      The ``numBins`` argument specifies how many bins the internal
      :ref:`OEFastROCSHistogram <OEFastROCS_OEFastROCSHistogram>` will have. The
      granularity of each bin is the determined by the range of the
      score divided by the number of bins. Note,
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Shape` and
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Color` have a range
      of 0.0-1.0, while
      :oe:const:`OEFastROCS::OEShapeDatabaseType::Combo` has a range
      of 0.0-2.0.

   .. oe:method:: GetCounts

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

         .. oe:api::

            OEULongLong GetCounts(bool blocking = false)

      .. oe:language:: python

         .. oe:api:: python

            GetCounts(blocking: bool = False) -> int

      Returns the current number of conformers already searched by a
      :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>`. This is a thread-safe
      function for querying the current progress of the database
      search. :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` will update the
      progress of this tracer through the
      :oe:meth:`OEFastROCS::OEDBTracer::Update` method from multiple
      threads. This function can be used by another thread to query
      that total progress.

      The optional ``blocking`` parameter specifies whether the call
      should wait until there has been an update to the tracer before
      returning. This can be useful for making progress updates not
      spin too rapidly reporting the same number every time.

   .. oe:method:: GetHistogram

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

         .. oe:api::

            OEFastROCSHistogram GetHistogram()

      .. oe:language:: python

         .. oe:api:: python

            GetHistogram() -> OEFastROCSHistogram

      Return a copy of the histogram currently accumulated in this
      database query as a :ref:`OEFastROCSHistogram <OEFastROCS_OEFastROCSHistogram>`
      object. This histogram will be empty if ``numBins`` passed to
      the constructor is ``0``.

      This is a thread-safe function for querying the current
      distribution of scores for the molecules already processed. The
      full histogram of the scores is not available until the value
      returned by :oe:meth:`OEFastROCS::OEDBTracer::GetCounts` is
      equal to :oe:meth:`OEFastROCS::OEDBTracer::GetTotal`.

   .. oe:method:: GetNumBins

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

         .. oe:api::

            size_t GetNumBins() const

      .. oe:language:: python

         .. oe:api:: python

            GetNumBins() -> int

      Return the number of bins to use for the score histogram during
      this particular query. Returning '0', the default, will indicate
      to :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` to skip
      histogram creation all together.

   .. oe:method:: GetTotal

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

         .. oe:api::

            OEULongLong GetTotal()

      .. oe:language:: python

         .. oe:api:: python

            GetTotal() -> int

      Return the total number of conformers to be processed.

      .. warning::

         It is possible for this function to return ``0`` for a short
         time after a call to
         :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or
         :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores`. So a
         ``0`` return value should be taken with a grain of salt of
         that possible race-condition.

   .. oe:method:: SetTotal

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

         .. oe:api::

            void SetTotal(OEULongLong total)

      .. oe:language:: python

         .. oe:api:: python

            SetTotal(total: int) -> None

      Called by :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` and
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` to set
      whatever the total number of conformers that will be processed.

   .. oe:method:: Update

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

         .. oe:api::

            void Update(OEULongLong step = 1,
                        const OEFastROCSHistogram* hist = NULL)

      .. oe:language:: python

         .. oe:api:: python

            Update(step: int = 1, hist: OEFastROCSHistogram = None) -> None

      Called by :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` and
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` from
      multiple threads to communicate the current progress of the search.
