org.hd.d.pg2k.ai.scorer
Class AbstractScorerCache

java.lang.Object
  org.hd.d.pg2k.ai.scorer.AbstractScorerCache

All Implemented Interfaces:

ScorerCacheIF

Direct Known Subclasses:

MiniScorerCacheImpl, ScorerCacheImpl

abstract class AbstractScorerCache
extends java.lang.Object
implements ScorerCacheIF

Shared abstract base to handle common Scorer cache tasks. Package-visible only for now to support initial cache implementations.

Author:

dhd

log

protected final SimpleLoggerIF log

Logger; never null.

population

protected final ScorerPopulation population

Scorer population (and cache of Scorer "goodness"); never null.

dataSource

protected final SimpleExhibitPipelineIF dataSource

Live data source for variables, exhibit data and metadata, etc; never null.

_rawScores

private final LRUMapAutoSizeForHitRate<Tuple.Pair<java.lang.String,Name.ExhibitFull>,Tuple.Pair<java.lang.Long,ScoreAndConf>> _rawScores

Size-limited cache of raw exhibit scores (and when computed); never null. Map from scorer name-and-parameters and exhibit name to ScoreAndConfidence and time computed.

This is a thread-safe map, with automatic LRU discarding of stale/unused values.

A lock can be held on this map to make compound operations atomic, though the lock should be held for as little time as possible so as to maximise available concurrency.

AbstractScorerCache

protected AbstractScorerCache(ScorerPopulation population,
                              SimpleExhibitPipelineIF dataSource,
                              SimpleLoggerIF log)

getDataSource

SimpleExhibitPipelineIF getDataSource()

Make internal dataSource available to classes in the same package only; never null.

size

public int size()

Get current population size; non-negative.

Specified by:

size in interface ScorerCacheIF

getPopulation

ScorerPopulation getPopulation()

Make population available to classes in the same package only; never null.

poll

public void poll()
          throws java.io.IOException

Poll to do incremental work; does nothing by default.

Specified by:

poll in interface ScorerCacheIF

Throws:

java.io.IOException

destroy

public void destroy()

Save work-in-progress if possible, and free up resources, ASAP. This may enable us to reduce work lost during a graceful system shutdown, but many shutdowns may not be graceful and so we should incrementally save/checkpoint too.

By default does nothing.

Specified by:

destroy in interface ScorerCacheIF

getCurrentScorersWithParameters

public java.util.Set<java.lang.String> getCurrentScorersWithParameters(boolean allowStale)

Current set of best-available Scorers with their parameters; never null but may be empty. This operation should always be relatively fast.

Specified by:

getCurrentScorersWithParameters in interface ScorerCacheIF

computeUnweightedScoreAndConfidence

public ScoreAndConf computeUnweightedScoreAndConfidence(Name.ExhibitFull exhibitName,
                                                        ScorerIF scorer,
                                                        boolean allowStale)
                                                 throws java.io.IOException

Description copied from interface: ScorerCacheIF

Computes the raw score [-1,+1] and confidence [0,+1] for the specified exhibit with the specified scorer and parameters; never null but may be (0,0). This is NOT moderated/weighted in the light of how well the scorer's predictions match reality; that requires an extra step.

Specified by:

computeUnweightedScoreAndConfidence in interface ScorerCacheIF

Parameters:

exhibitName - valid full exhibit name

scorer - instance of the Scorer; never null

allowStale - if true then allow a stale value from cache, else throw an exception if nothing is currently available

Returns:

(0,0) if named scorer is not available, cannot be used with the specified parameters, or cannot be applied to the indicated exhibit (eg because of the exhibit type or the exhibit does not exist); else returns a non-null ScoreAndConf value

Throws:

java.io.IOException

getCachedCompositeScoreAndConfidence

public ScoreAndConf getCachedCompositeScoreAndConfidence(Name.ExhibitFull exhibitName,
                                                         boolean allowStale)
                                                  throws java.io.IOException

Default implementation is uncached; always returns null.

Specified by:

getCachedCompositeScoreAndConfidence in interface ScorerCacheIF

Parameters:

exhibitName - valid full exhibit name

allowStale - if true then allow a stale value from cache, else throw an exception if nothing is currently available

Returns:

null if nothing already available in cache, else (0,0) if named scorer is not available, cannot be used with the specified parameters, or cannot be applied to the indicated exhibit (eg because of the exhibit type or the exhibit does not exist); else returns a non-null ScoreAndConf value

Throws:

java.io.IOException

computeScorerWeighting

public ScoreAndConf computeScorerWeighting(java.lang.String scorerNameAndParameters,
                                           boolean allowStale,
                                           java.lang.String source)
                                    throws java.io.IOException

Description copied from interface: ScorerCacheIF

ScoreAndConfidence for the given Scorer over all exhibit types; never null but may be (0,0) where the scorer is unknown or untested. Essentially the result of this should be multiplied by the result for each exhibit (for the same scorer and parameters) to normalise the predicted score and confidence for the exhibit.

Some results will be cached (typically those from the base/current Scorer lists) while other may have to be computed each time, which may be slow.

The source parameter can be used to track which mechanisms are most effective at generating improvements in the population, and could, for example, to spend more time on those that are most effective right now.

Specified by:

computeScorerWeighting in interface ScorerCacheIF

Parameters:

scorerNameAndParameters - the name and parameters of the scorer; never null

allowStale - if true then allow a stale or low-confidence value from cache, else throw an exception if nothing is currently available and we cannot quickly compute enough points to increase our confidence

source - the name of the mechanism used to generate this Scorer value, or null if none

Returns:

the score represents the correlation with the underlying votes (and whatever the scoring is measured against) with MAX meaning perfect correlation, 0 meaning no correlation, and -MAX meaning perfectly wrong answers all the time, and the confidence 0 if we have no (or very/too few) data points and approaching MAX as we have a large (enough) number of data points

Throws:

java.io.IOException

getScorerInstance

public ScorerIF getScorerInstance(java.lang.String nameAndParameters)

Description copied from interface: ScorerCacheIF

Get Scorer instance given the Scorer{:value=name}* format; null if no such Scorer available. Any instance returned may be a shared/cached instance rather than a new instance.

Specified by:

getScorerInstance in interface ScorerCacheIF

offerExternalScorer

public boolean offerExternalScorer(java.lang.String externalScorerNameAndParameters)

Non-blocking attempt to queue an externally-supplied Scorer value; returns true if accepted. This default implementation always returns false.

Specified by:

offerExternalScorer in interface ScorerCacheIF

canAcceptMoreExternalScorers

public boolean canAcceptMoreExternalScorers()

Returns true if this cache can accept (many) more external-supplied Scorer values. This default implementation always returns false.

Specified by:

canAcceptMoreExternalScorers in interface ScorerCacheIF

hasQueuedExternalScorer

public boolean hasQueuedExternalScorer()

Returns true if at least once external Scorer is queued waiting to be processed. This default implementation always returns false.

Specified by:

hasQueuedExternalScorer in interface ScorerCacheIF