OEDBTracerBase

class OEDBTracerBase

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

Warning

OEShapeDatabase.GetScores and 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:

• OEDBTracer

GetNumBins

size_t GetNumBins() const

Return the number of bins to use for the score histogram during this particular query. Returning ‘0’, the default, will indicate to OEShapeDatabase.GetScores or OEShapeDatabase.GetSortedScores to skip histogram creation all together.

SetTotal

void SetTotal(OEULongLong total)=0

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

Update

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

Called many times by OEShapeDatabase.GetScores or OEShapeDatabase.GetSortedScores from many operating system threads so this function should be thread-safe. The 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 OEShapeDatabase search threads, so forward progress can not be made if this function is costly.

The optional hist argument is a OEFastROCSHistogram to accumulate into a master histogram for the entire query. Typically, OEShapeDatabase.GetScores and 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 OEDBTracerBase should guarantee the thread-safety of this method.