FARGOS/VISTA Object Management Environment Core  ..
FARGOS/VISTA Object Management Environment Core Table of Contents
FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE > Class Template Reference

Fast map lookup table. More...

#include <fastLookupTable.hpp>

Classes

class  FastLookupTableIterator
 Iterator for FastLookupTable. More...
 

Public Member Functions

 FastLookupTable ()
 Construct a FastLookupTable object. More...
 
virtual ~FastLookupTable ()
 
RECORD_TYPE * findRecord (const unsigned char *key, const uint_fast32_t keyLen) const OME_ALWAYS_OPTIMIZE("-O3")
 Find record in mapping table. More...
 
RECORD_TYPE * findRecord (const char *key) const OME_ALWAYS_INLINE OME_ALWAYS_OPTIMIZE("-O3")
 Convenience interface for working with C-string keys. More...
 
RECORD_TYPE * findRecord (const std::string &key) const OME_ALWAYS_INLINE OME_ALWAYS_OPTIMIZE("-O3")
 Convenience interface for working with std::string keys. More...
 
int addRecord (const unsigned char *key, const uint_fast32_t keyLen, RECORD_TYPE *rec)
 Add a record to mapping table. More...
 
int addRecord (const char *key, RECORD_TYPE *rec) OME_ALWAYS_INLINE
 Convenience interface for working with C-string keys. More...
 
int addRecord (const std::string &key, RECORD_TYPE *rec) OME_ALWAYS_INLINE
 Convenience interface for working with std::string keys. More...
 
FastLookupTableIterator begin ()
 Get initial iterator. More...
 

Protected Types

enum  { ELEMENT_RANGE = (LARGEST_CHAR - SMALLEST_CHAR) + 1 }
 

Protected Member Functions

RECORD_TYPE * findRecordInSpillover (const BinaryBlock_struct key) const
 
RECORD_TYPE * findRecordInSpillover (const unsigned char *key, const uint_fast32_t len) const OME_ALWAYS_INLINE
 
void addRecordToSpillover (const unsigned char *key, const uint_fast32_t keyLen, RECORD_TYPE *rec) OME_ALWAYS_INLINE
 

Protected Attributes

RECORD_TYPE * record [ELEMENT_RANGE]
 pointer to records that end at this position More...
 
FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE > * nextLevel [ELEMENT_RANGE]
 pointer to chain of records that had character in this position More...
 
std::map< BinaryBlock_struct, RECORD_TYPE *, LT_KEY_COMPARE > outOfBoundEntries
 Map to handle entries that do not fit: character out of bounds or too long. More...
 

Detailed Description

template<typename RECORD_TYPE, const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
class FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >

Fast map lookup table.

Parameters
RECORD_TYPEidentifies the type of the records to be referenced by the map.
MAX_LOOKAHEADspecifies how many characters are to be used for fixed fanout tables.
SMALLEST_CHARidentifies the smallest expected character value to be seen in a key.
LARGEST_CHARidentifies the largest expected character value to be seen in a key.
LT_KEY_COMPAREis the comparison routine for the key. The default routine does a binary comparison and would rarely need to be replaced; however, this can be useful to handle special modifiers embedded within a key.
Note

If a character appears outside the range of [SMALLEST_CHAR,LARGEST_CHAR], the key will still be accepted. It will be added to the local out-of-bounds list, which incurs O(ln N) additional overhead where N is the number of exceptional elements recorded at that level.

If a key is longer than the MAX_LOOKAHEAD limit, it will still be accepted. It is added to the out-of-bounds list at the leaf element of the fixed fanout tables. The default comparison routine honors the key length.

The MAX_LOOKAHEAD parameter has the greatest effect on trading space for time: the amount of space required is proportional to (LARGEST_CHAR - SMALLEST_CHAR) raised to the MAX_LOOKAHEAD power. Simply put: the amount of space required increases exponentially as MAX_LOOKAHEAD increases and it becomes increasingly infeasible to fit all of the data into a CPU's cache. If the keys are not uniformly distributed, many of the fixed fanout tables will be sparse, which lowers the effectiveness of the CPU's cache with respect to whatever data was retrieved.

Arbitrary binary keys can be handled using SMALLEST_CHAR set to 0 and LARGEST_CHAR set to 255; however, cache efficiency goes down and storage requirements go up as the range is widened. With MAX_LOOKAHEAD=2, about 1 megabyte will be required for the data structures. Increasing MAX_LOOKAHEAD to 3 raises the storage requirements to about 256 megabytes.

Member Enumeration Documentation

◆ anonymous enum

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
anonymous enum
protected
Enumerator
ELEMENT_RANGE 

Constructor & Destructor Documentation

◆ FastLookupTable()

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::FastLookupTable ( )
inline

◆ ~FastLookupTable()

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
virtual FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::~FastLookupTable ( )
inlinevirtual

Member Function Documentation

◆ addRecord() [1/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
int FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord ( const char *  key,
RECORD_TYPE *  rec 
)
inline

Convenience interface for working with C-string keys.

Parameters
keypoints to the null-terminated string key
recpoints to the record to be added
Warning
The key contents are not copied and must be retained at the location specified by key.

References FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord().

◆ addRecord() [2/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
int FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord ( const std::string &  key,
RECORD_TYPE *  rec 
)
inline

Convenience interface for working with std::string keys.

Parameters
keyis a reference to a std::string holding the string key
recpoints to the record to be added
Warning
The key contents are not copied and must be maintained at the current location for the lifetime of the entry. Caution is recommended to ensure that the data is not subsequently deleted.

References FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord().

◆ addRecord() [3/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
int FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord ( const unsigned char *  key,
const uint_fast32_t  keyLen,
RECORD_TYPE *  rec 
)
inline

Add a record to mapping table.

Parameters
keypoints to the start of the key
keyLenindicates the length of the key; it must be greater than 0.
recis a pointer to the record which is to be stored
Return values
1indicates it was added within the MAX_LOOKAHEAD tables.
2indicates it had characters outside the range
3indicates it was longer than MAX_LOOKAHEAD.
Warning
The contents of the key are not copied and must be maintained at the specified location for the lifetime of the record. An ideal solution is for the key to be located within the record itself and thus share its fate.

References FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecordToSpillover(), app(), AS_TEXT_BUFFER, FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::ELEMENT_RANGE, LOG_COMPONENT_CERR, LOG_ENDLINE, FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::nextLevel, OME_EXPECT_FALSE, OME_EXPECT_TRUE, OME_PREFETCH, and FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::record.

Referenced by FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecord().

◆ addRecordToSpillover()

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
void FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::addRecordToSpillover ( const unsigned char *  key,
const uint_fast32_t  keyLen,
RECORD_TYPE *  rec 
)
inlineprotected

◆ begin()

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
FastLookupTableIterator FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::begin ( )
inline

Get initial iterator.

◆ findRecord() [1/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecord ( const char *  key) const
inline

Convenience interface for working with C-string keys.

Parameters
keypoints to the null-terminated string.

References FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecord().

◆ findRecord() [2/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecord ( const std::string &  key) const
inline

Convenience interface for working with std::string keys.

Parameters
keyreferences to std::string holding the key.

References FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecord().

◆ findRecord() [3/3]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecord ( const unsigned char *  key,
const uint_fast32_t  keyLen 
) const
inline

◆ findRecordInSpillover() [1/2]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecordInSpillover ( const BinaryBlock_struct  key) const
inlineprotected

◆ findRecordInSpillover() [2/2]

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::findRecordInSpillover ( const unsigned char *  key,
const uint_fast32_t  len 
) const
inlineprotected

Member Data Documentation

◆ nextLevel

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
FastLookupTable<RECORD_TYPE,MAX_LOOKAHEAD,SMALLEST_CHAR,LARGEST_CHAR,LT_KEY_COMPARE>* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::nextLevel[ELEMENT_RANGE]
protected

◆ outOfBoundEntries

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
std::map<BinaryBlock_struct,RECORD_TYPE *,LT_KEY_COMPARE> FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::outOfBoundEntries
protected

◆ record

template<typename RECORD_TYPE , const uint_fast8_t MAX_LOOKAHEAD = 4, const unsigned char SMALLEST_CHAR = 'A', const unsigned char LARGEST_CHAR = 'Z', typename LT_KEY_COMPARE = FastLookupUtils::ltBinaryBlock>
RECORD_TYPE* FastLookupTable< RECORD_TYPE, MAX_LOOKAHEAD, SMALLEST_CHAR, LARGEST_CHAR, LT_KEY_COMPARE >::record[ELEMENT_RANGE]
protected

The documentation for this class was generated from the following file:
Generated: Fri Jul 31 2020 18:19:16
Support Information