.. oe:namespace:: OEFastROCS



.. meta::
   :keywords: OEDBTracerBase, DBTracerBase


.. _OEFastROCS_OEDBTracerBase:

.. oe:class:: OEDBTracerBase

   .. oe:api::

      class OEDBTracerBase

   Abstract base class used by :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>`
   to track the progress of an individual search against the
   database. Users should derive from this class and pass the derived
   class into :oe:meth:`OEFastROCS::OEShapeDatabaseOptions::SetTracer`
   for the options object later passed into
   :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or
   :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores`.

   .. warning::

      :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` and
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` are
      multi-threaded functions, so the ``Update`` method implemented
      by a derived class should be thread-safe.

   The following classes derive from this class and should be used in
   preference of creating a custom tracer:

    * :ref:`OEDBTracer <OEFastROCS_OEDBTracer>`

   .. 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:: SetTotal

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

         .. oe:api::

            void SetTotal(OEULongLong total)=0

      .. oe:language:: python

         .. oe:api:: python

            SetTotal(total: int) -> None

      Called once by :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores`
      or :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` in a
      single thread to indicate the total number of conformers that
      will be searched.

   .. oe:method:: Update

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

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

      Called many times by
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` or
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` from
      many operating system threads so this function should be
      thread-safe. The :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` object
      will pass in a large ``step`` size to optimize the number of
      times this function is called, typically only hundreds of times
      will this method be called for a database containing millions of
      conformers. The ``step`` corresponds to the number of conformers
      already searched. Even so, this function should be implemented
      with very efficiently as it is called by the
      :ref:`OEShapeDatabase <OEFastROCS_OEShapeDatabase>` search threads, so forward
      progress can not be made if this function is costly.

      The optional ``hist`` argument is a
      :ref:`OEFastROCSHistogram <OEFastROCS_OEFastROCSHistogram>` to accumulate into a
      master histogram for the entire query. Typically,
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetScores` and
      :oe:meth:`OEFastROCS::OEShapeDatabase::GetSortedScores` will
      submit will call this method once for very large chunks of the
      database. This makes the synchronization point of calling this
      function very minimal to the overall runtime of the query. If a
      ``NULL`` pointer is passed, the default, no histogram
      accumulation will occur.

      .. warning::

         The implementer of a sub-class of
         :ref:`OEDBTracerBase <OEFastROCS_OEDBTracerBase>` should guarantee the
         thread-safety of this method.
