Implements sequential in-line evaluation of a criterion on a set of subset candidates. More...

#include <candidate_evaluator_sequential.hpp>

Inheritance diagram for FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >:

Public Types
typedef Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >	parent
	the abstract Candidate_Evaluator interface this class implements
typedef parent::PCriterion	PCriterion
	shared pointer to the criterion this engine evaluates candidates against
typedef parent::PSubset	PSubset
	shared pointer to a candidate feature subset
typedef parent::PResultTracker	PResultTracker
	shared pointer to the result tracker fed during evaluate_stream()
typedef parent::Generator	Generator
	see Candidate_Evaluator::Generator
typedef parent::ResultCallback	ResultCallback
	see Candidate_Evaluator::ResultCallback
typedef parent::BestCallback	BestCallback
	see Candidate_Evaluator::BestCallback
typedef parent::BetterPredicate	BetterPredicate
	see Candidate_Evaluator::BetterPredicate
Public Types inherited from FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
typedef std::shared_ptr< CRITERION >	PCriterion
	shared pointer to the criterion this engine evaluates candidates against
typedef std::shared_ptr< SUBSET >	PSubset
	shared pointer to a candidate feature subset
typedef std::shared_ptr< Result_Tracker< RETURNTYPE, SUBSET > >	PResultTracker
typedef std::function< bool(SUBSET &)>	Generator
	fills sub with the next candidate, returns false when no candidate remains (in the threaded implementation calls are serialized under a lock)
typedef std::function< void(const RETURNTYPE, const PSubset &, const DIMTYPE)>	ResultCallback
	fired once per evaluated batch candidate: (criterion value, candidate, feature tag as passed to add_candidate)
typedef std::function< void(const int, const unsigned long long, const RETURNTYPE, const PSubset &)>	BestCallback
typedef std::function< bool(const RETURNTYPE, const PSubset &, const RETURNTYPE, const PSubset &)>	BetterPredicate
	returns true if (value,subset) is better than (best value,best subset) - encodes per-search tie-breaking for evaluate_stream()

Public Member Functions
virtual unsigned int	get_max_threads () const override
	1 in the sequential implementation
virtual bool	is_threaded () const override
	true for the threaded engine (any --threads value), false for the sequential one – distinguishes the engine kind, not whether get_max_threads()>1
virtual void	initialize (const PCriterion &crit, const DIMTYPE max_candidates, ResultCallback on_result=ResultCallback()) override
	starts a new batch; max_candidates must bound the number of add_candidate() calls to follow
virtual bool	add_candidate (const PSubset &sub, const DIMTYPE feature=0) override
	adds one candidate to the current batch; `sub` is copied, `feature` is an opaque tag handed back by the callbacks. Returns false on evaluation failure (sequential) or when more than the announced max_candidates candidates are added (threaded)
virtual bool	collect () override
	nothing is left pending in this engine (every candidate was evaluated inside add_candidate()), so collect() only reports the batch outcome: true if at least one candidate was evaluated and none failed
virtual bool	getBestResult (RETURNTYPE &result, PSubset &sub, DIMTYPE &feature) override
	completes the batch first, then hands out its best candidate (`sub` is set to the engine's own subset object, its contents are not copied and are overwritten by the following batch - copy them if they must outlive it); earliest added wins ties; false if the batch evaluated nothing or an evaluation failed
virtual bool	evaluate_stream (Generator generator, const PCriterion &crit, const PResultTracker tracker, BetterPredicate better, BestCallback on_best, RETURNTYPE &result, const PSubset bestsub) override
	Evaluates candidates produced by `generator` until it reports exhaustion, keeping the best one.
virtual std::ostream &	print (std::ostream &os) const override
	writes a human-readable identification of the engine; base default writes nothing
Public Member Functions inherited from FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >
virtual void	invalidate_clones ()
	Drops any cached per-worker criterion clones, so that the next batch or stream re-clones from the criterion it is handed.

Protected Attributes
PCriterion	_crit
	the criterion supplied to initialize(), evaluated in-line by add_candidate()
ResultCallback	_on_result
	the per-result callback supplied to initialize(), fired synchronously from add_candidate()
PSubset	_bestsub
	the best candidate seen so far in the current batch (only the best is retained, not the whole batch)
bool	_best_available
	true once at least one candidate has been evaluated successfully in the current batch
RETURNTYPE	_bestval
	criterion value of _bestsub
DIMTYPE	_bestfeature
	the feature tag passed to add_candidate() for _bestsub
DIMTYPE	_evaluated
	number of candidates evaluated in the current batch (collect() requires at least one)
bool	_failed
	set when a criterion evaluate() call returned false; makes collect() and getBestResult() report failure (the threaded engine's _batch_failed semantics)

Detailed Description

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>
class FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >

Implements sequential in-line evaluation of a criterion on a set of subset candidates.

The sequential counterpart of Candidate_Evaluator_Threaded: candidates are evaluated immediately in the caller's thread. In batch mode add_candidate() evaluates on the spot and fires the per-result callback synchronously, so evaluations and the caller's own output stay strictly interleaved in add order. Only the running best candidate is stored - memory does not grow with the batch size. The criterion is used directly (never cloned), so no thread-safety or clone-staleness concerns apply here.

Member Function Documentation

◆ add_candidate()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::add_candidate	(	const PSubset &	sub,
		const DIMTYPE	feature = 0 )

inlineoverridevirtual

adds one candidate to the current batch; sub is copied, feature is an opaque tag handed back by the callbacks. Returns false on evaluation failure (sequential) or when more than the announced max_candidates candidates are added (threaded)

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ collect()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::collect ( )

inlineoverridevirtual

nothing is left pending in this engine (every candidate was evaluated inside add_candidate()), so collect() only reports the batch outcome: true if at least one candidate was evaluated and none failed

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ evaluate_stream()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::evaluate_stream	(	Generator	generator,
		const PCriterion &	crit,
		const PResultTracker	tracker,
		BetterPredicate	better,
		BestCallback	on_best,
		RETURNTYPE &	result,
		const PSubset	bestsub )

inlineoverridevirtual

Evaluates candidates produced by generator until it reports exhaustion, keeping the best one.

Parameters

generator	called to fill the next candidate; false from it ends the stream
crit	the criterion to evaluate with; must be initialize()d
tracker	result tracker to log every evaluated candidate into, or null for no tracking
better	the search's own "is strictly better" predicate, deciding both improvement and tie-breaking
on_best	fired on each improvement; may be empty
result	receives the best criterion value; meaningful only if the call returns true
bestsub	non-null subset dimensioned for the full feature set, receiving the best candidate

Returns: false if no candidate was evaluated successfully (empty stream or criterion failure)

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ get_max_threads()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual unsigned int FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::get_max_threads ( ) const

inlineoverridevirtual

1 in the sequential implementation

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ getBestResult()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::getBestResult	(	RETURNTYPE &	result,
		PSubset &	sub,
		DIMTYPE &	feature )

inlineoverridevirtual

completes the batch first, then hands out its best candidate (sub is set to the engine's own subset object, its contents are not copied and are overwritten by the following batch - copy them if they must outlive it); earliest added wins ties; false if the batch evaluated nothing or an evaluation failed

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ initialize()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual void FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::initialize	(	const PCriterion &	crit,
		const DIMTYPE	max_candidates,
		ResultCallback	on_result = ResultCallback() )

inlineoverridevirtual

starts a new batch; max_candidates must bound the number of add_candidate() calls to follow

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ is_threaded()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual bool FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::is_threaded ( ) const

inlineoverridevirtual

true for the threaded engine (any --threads value), false for the sequential one – distinguishes the engine kind, not whether get_max_threads()>1

Implements FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

◆ print()

template<class RETURNTYPE, typename DIMTYPE, class SUBSET, class CRITERION>

virtual std::ostream & FST::Candidate_Evaluator_Sequential< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >::print ( std::ostream & os ) const

inlineoverridevirtual

writes a human-readable identification of the engine; base default writes nothing

Reimplemented from FST::Candidate_Evaluator< RETURNTYPE, DIMTYPE, SUBSET, CRITERION >.

The documentation for this class was generated from the following file:

/Users/psms/dev/devtest1/_src_search/candidate_evaluator_sequential.hpp

Public Types

Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ add_candidate()

◆ collect()

◆ evaluate_stream()

◆ get_max_threads()

◆ getBestResult()

◆ initialize()

◆ is_threaded()

◆ print()