/*++ Copyright (c) 1998-2000 Microsoft Corporation Module Name : LKR-hash.h Abstract: Declares LKRhash: a fast, scalable, cache- and multiprocessor-friendly hash table Authors: Paul (Per-Ake) Larson, PALarson@microsoft.com, July 1997 Murali R. Krishnan (MuraliK) George V. Reilly (GeorgeRe) 06-Jan-1998 --*/ #ifndef __LKR_HASH_H__ #define __LKR_HASH_H__ /* Enable STL-style iterators */ #ifndef LKR_NO_STL_ITERATORS # define LKR_STL_ITERATORS 1 #endif /* !LKR_NO_STL_ITERATORS */ /* Enable call-back, table visitor routines */ #ifndef LKR_NO_APPLY_IF # define LKR_APPLY_IF #endif /* !LKR_NO_APPLY_IF */ /* Expose the table's ReadLock and WriteLock routines */ #ifndef LKR_NO_EXPOSED_TABLE_LOCK # define LKR_EXPOSED_TABLE_LOCK #endif /* !LKR_NO_EXPOSED_TABLE_LOCK */ #ifndef __IRTLMISC_H__ # include #endif /* !__IRTLMISC_H__ */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ typedef struct LkrHashTable* PLkrHashTable; /*-------------------------------------------------------------------- * Possible return codes from LKR_functions and TypedLkrHashTable */ enum LK_RETCODE { /* severe errors < 0 */ LK_UNUSABLE = -99, /* Table corrupted: all bets are off */ LK_ALLOC_FAIL, /* ran out of memory */ LK_BAD_ITERATOR, /* invalid iterator; e.g., points to another table */ LK_BAD_RECORD, /* invalid record; e.g., NULL for LKR_InsertRecord */ LK_BAD_PARAMETERS, /* invalid parameters; e.g., NULL fnptrs to ctor */ LK_NOT_INITIALIZED, /* LKRHashTableInit was not called */ LK_BAD_TABLE, /* Called with invalid PLkrHashTable */ LK_SUCCESS = 0, /* everything's okay */ LK_KEY_EXISTS, /* key already present for LKR_InsertRecord(no-overwrite) */ LK_NO_SUCH_KEY, /* key not found */ LK_NO_MORE_ELEMENTS,/* iterator exhausted */ }; #define LKR_SUCCEEDED(lkrc) ((lkrc) >= LK_SUCCESS) /*-------------------------------------------------------------------- * Size parameter to LKR_CreateTable */ enum LK_TABLESIZE { LK_SMALL_TABLESIZE= 1, /* < 200 elements */ LK_MEDIUM_TABLESIZE= 2, /* 200...10,000 elements */ LK_LARGE_TABLESIZE= 3, /* 10,000+ elements */ }; /*-------------------------------------------------------------------- * Creation flag parameter to LKR_CreateTable */ enum { LK_CREATE_DEFAULT = 0, /* 0 is an acceptable default */ LK_CREATE_MULTIKEYS = 0x0001, /* Allow multiple identical keys? */ }; /*-------------------------------------------------------------------- * Initialization flag parameters to LKR_Initialize */ enum { LK_INIT_DEFAULT = 0, /* 0 is an acceptable default */ LK_INIT_DEBUG_SPEW = 0x1000, /* Enable debug output: debug version only */ }; /*-------------------------------------------------------------------- * Reference Counting and Lifetime Management * * Increment the reference count of a record before returning it from * LKR_FindKey. It's necessary to do it in LKR_FindKey itself while the * bucket is still locked, rather than one of the wrappers, to avoid race * conditions. Similarly, the reference count is incremented in * LKR_InsertRecord and decremented in LKR_DeleteKey. Finally, if an old * record is overwritten in LKR_InsertRecord, its reference count is * decremented. * * Summary of calls to AddRefRecord * +1: add a new reference or owner * - LKR_InsertRecord * - LKR_FindKey * - IncrementIterator * -1: delete a reference => release an owner * - LKR_InsertRecord (overwrite old record with same key) * - LKR_DeleteKey, LKR_DeleteRecord * - ApplyIf(LKP_DELETE), DeleteIf * - IncrementIterator (previous record), CloseIterator, Erase(iter) * - LKR_Clear, table destructor * 0: no change (not called) * - LKR_FindRecord (by definition, you already have a ref to the record) * * It's up to you to decrement the reference count when you're finished * with it after retrieving it via LKR_FindKey (e.g., you could call * pht->AddRefRecord(pRec, LKAR_EXPLICIT_RELEASE)) and to determine the * semantics of what this means. The hashtable itself has no notion of * reference counts; this is merely to help with the lifetime management * of the record objects. */ /* These reason codes help in debugging refcount leaks */ enum LK_ADDREF_REASON { /* negative reasons => decrement refcount => release ownership */ LKAR_EXPLICIT_RELEASE = -29, /* user calls ht.AddRefRecord to */ /* explicitly release a record */ LKAR_DELETE_KEY = -28, /* DeleteKey() */ LKAR_DELETE_RECORD = -27, /* DeleteRecord() */ LKAR_INSERT_RELEASE = -26, /* InsertRecord overwrites prev record */ LKAR_CLEAR = -25, /* Clear() */ LKAR_DTOR = -24, /* hash table destructor */ LKAR_APPLY_DELETE = -23, /* Apply[If] LKP_(PERFORM|_DELETE) */ LKAR_DELETE_IF_DELETE = -22, /* DeleteIf LKP_(PERFORM|_DELETE) */ LKAR_ITER_RELEASE = -21, /* ++iter releases previous record */ LKAR_ITER_ASSIGN_RELEASE = -20, /* iter.operator= releases prev rec */ LKAR_ITER_DTOR = -19, /* ~iter */ LKAR_ITER_ERASE = -18, /* Erase(iter): iter releases record */ LKAR_ITER_ERASE_TABLE = -17, /* Erase(iter); table releases record */ LKAR_ITER_CLOSE = -16, /* CloseIterator (obsolete) */ /* positive reasons => increment refcount => add an owner */ LKAR_INSERT_RECORD = +11, /* InsertRecord() */ LKAR_FIND_KEY = +12, /* FindKey() */ LKAR_ITER_ACQUIRE = +13, /* ++iter acquires next record */ LKAR_ITER_COPY_CTOR = +14, /* iter copy constructor acquires rec */ LKAR_ITER_ASSIGN_ACQUIRE = +15, /* iter.operator= acquires new rec */ LKAR_ITER_INSERT = +16, /* Insert(iter) */ LKAR_ITER_FIND = +17, /* Find(iter) */ LKAR_EXPLICIT_ACQUIRE = +18, /* user calls ht.AddRefRecord to */ /* explicitly acquire a ref to a rec */ }; /* Convert an LK_ADDREF_REASON to a string representation. * Useful for debugging. */ IRTL_DLLEXP const char* LKR_AddRefReasonAsString( LK_ADDREF_REASON lkar); /*-------------------------------------------------------------------- * Callback functions needed by table: * ExtractKey, CalcKeyHash, EqualKeys, AddRefRecord * Internally, records are handled as `const void*' and * keys are handled as `const DWORD_PTR'. The latter allows for * keys to be numbers as well as pointers (polymorphism). */ /* Use types defined in recent versions of the Platform SDK in . */ #ifndef _W64 typedef DWORD DWORD_PTR; /* integral type big enough to hold a pointer */ #endif /* Given a record, return its key. Assumes that the key is embedded in * the record, or at least somehow derivable from the record. For * completely unrelated keys & values, a wrapper class should use * something like STL's pair template to aggregate them * into a record. */ typedef const DWORD_PTR (WINAPI *LKR_PFnExtractKey) ( const void* pvRecord); /* Given a key, return its hash signature. The hashing functions in * hashfn.h (or something that builds upon them) are suggested. */ typedef DWORD (WINAPI *LKR_PFnCalcKeyHash) ( const DWORD_PTR pnKey); /* Compare two keys for equality; e.g., _stricmp, memcmp, operator== */ typedef BOOL (WINAPI *LKR_PFnEqualKeys) ( const DWORD_PTR pnKey1, const DWORD_PTR pnKey2); /* Adjust the reference count of a record. See the earlier discussion * of reference counting and lifetime management. */ typedef void (WINAPI *LKR_PFnAddRefRecord)( const void* pvRecord, LK_ADDREF_REASON lkar); #ifdef LKR_APPLY_IF /*-------------------------------------------------------------------- * Apply, ApplyIf, and DeleteIf provide one way to visit (enumerate) all * records in a table. */ /*-------------------------------------------------------------------- * Return codes from PFnRecordPred. */ enum LK_PREDICATE { LKP_ABORT = 1, /* Stop walking the table immediately */ LKP_NO_ACTION = 2, /* No action, just keep walking */ LKP_PERFORM = 3, /* Perform action and continue walking */ LKP_PERFORM_STOP = 4, /* Perform action, then stop */ LKP_DELETE = 5, /* Delete record and keep walking */ LKP_DELETE_STOP = 6, /* Delete record, then stop */ }; /*-------------------------------------------------------------------- * Return codes from PFnRecordAction. */ enum LK_ACTION { LKA_ABORT = 1, /* Stop walking the table immediately */ LKA_FAILED = 2, /* Action failed; continue walking the table */ LKA_SUCCEEDED = 3, /* Action succeeded; continue walking the table */ }; /*-------------------------------------------------------------------- * Parameter to Apply and ApplyIf. */ enum LK_LOCKTYPE { LKL_READLOCK = 1, /* Lock the table for reading (for constness) */ LKL_WRITELOCK = 2, /* Lock the table for writing */ }; /* LKR_ApplyIf() and LKR_DeleteIf(): Does the record match the predicate? */ typedef LK_PREDICATE (WINAPI *LKR_PFnRecordPred) ( const void* pvRecord, void* pvState); /* LKR_Apply() et al: Perform action on record. */ typedef LK_ACTION (WINAPI *LKR_PFnRecordAction)( const void* pvRecord, void* pvState); #endif /* LKR_APPLY_IF */ /* Initialize the global variables needed by other LKR routines. */ IRTL_DLLEXP BOOL LKR_Initialize( DWORD dwInitFlags); /* Clean up the global variables needed by other LKR routines. */ IRTL_DLLEXP void LKR_Terminate(); /* Create a new LkrHashTable * Returns pointer to new table if successful. NULL, otherwise. * The table must be destroyed with LKR_DeleteTable. */ IRTL_DLLEXP PLkrHashTable LKR_CreateTable( LPCSTR pszName, /* Identify the table for debugging */ LKR_PFnExtractKey pfnExtractKey, /* Extract key from record */ LKR_PFnCalcKeyHash pfnCalcKeyHash, /* Calculate hash signature of key */ LKR_PFnEqualKeys pfnEqualKeys, /* Compare two keys */ LKR_PFnAddRefRecord pfnAddRefRecord,/* AddRef in LKR_FindKey, etc */ LK_TABLESIZE nTableSize, /* Small/Med/Large number of elements*/ DWORD fCreateFlags /* Mixture of LK_CREATE_* flags. */ ); /* Destroy an LkrHashTable created by LKR_CreateTable. */ IRTL_DLLEXP void LKR_DeleteTable( PLkrHashTable plkr); /* Insert a new record into hash table. * Returns LKR_SUCCESS if all OK, LKR_KEY_EXISTS if same key already * exists (unless fOverwrite), LKR_ALLOC_FAIL if out of space, * or LKR_BAD_RECORD for a bad record. * If fOverwrite is set and a record with this key is already present, * it will be overwritten. If there are multiple records with this key, * only the first will be overwritten. */ IRTL_DLLEXP LK_RETCODE LKR_InsertRecord( PLkrHashTable plkr, const void* pvRecord, BOOL fOverwrite); /* Delete record with the given key from the table. Does not actually delete * record from memory, just calls AddRefRecord(LKAR_DELETE_KEY); * Returns LKR_SUCCESS if all OK, or LKR_NO_SUCH_KEY if not found * If fDeleteAllSame is set, all records that match pnKey will be deleted * from the table; otherwise, only the first matching record is deleted. */ IRTL_DLLEXP LK_RETCODE LKR_DeleteKey( PLkrHashTable plkr, const DWORD_PTR pnKey, BOOL fDeleteAllSame); /* Delete a record from the table, if present. * Returns LKR_SUCCESS if all OK, or LKR_NO_SUCH_KEY if not found */ IRTL_DLLEXP LK_RETCODE LKR_DeleteRecord( PLkrHashTable plkr, const void* pvRecord); /* Find record with given key. * Returns: LKR_SUCCESS, if record found (record is returned in *ppvRecord) * LKR_NO_SUCH_KEY, if no record with given key value was found * LKR_BAD_RECORD, if ppvRecord is invalid * LKR_UNUSABLE, if hash table not in usable state * Note: the record is AddRef'd. You must decrement the reference * count when you are finished with the record (if you're implementing * refcounting semantics). */ IRTL_DLLEXP LK_RETCODE LKR_FindKey( PLkrHashTable plkr, const DWORD_PTR pnKey, const void** ppvRecord); /* Sees if the record is contained in the table * Returns: LKR_SUCCESS, if record found * LKR_NO_SUCH_KEY, if record is not in the table * LKR_BAD_RECORD, if pvRecord is invalid * LKR_UNUSABLE, if hash table not in usable state * Note: the record is *not* AddRef'd. By definition, the caller * already has a reference to it. */ IRTL_DLLEXP LK_RETCODE LKR_FindRecord( PLkrHashTable plkr, const void* pvRecord); #ifdef LKR_APPLY_IF /* Walk the hash table, applying pfnAction to all records. * Locks one subtable after another with either a (possibly * shared) readlock or a writelock, according to lkl. * Loop is aborted if pfnAction ever returns LKA_ABORT. * Returns the number of successful applications. */ IRTL_DLLEXP DWORD LKR_Apply( PLkrHashTable plkr, LKR_PFnRecordAction pfnAction, void* pvState, LK_LOCKTYPE lkl); /* Walk the hash table, applying pfnAction to any records that match * pfnPredicate. Locks one subtable after another with either * a (possibly shared) readlock or a writelock, according to lkl. * Loop is aborted if pfnAction ever returns LKA_ABORT. * Returns the number of successful applications. */ IRTL_DLLEXP DWORD LKR_ApplyIf( PLkrHashTable plkr, LKR_PFnRecordPred pfnPredicate, LKR_PFnRecordAction pfnAction, void* pvState, LK_LOCKTYPE lkl); /* Delete any records that match pfnPredicate. * Locks one subtable after another with a writelock. * Returns the number of deletions. * * Do *not* walk the hash table by hand with an iterator and call * LKR_DeleteKey. The iterator will end up pointing to garbage. */ IRTL_DLLEXP DWORD LKR_DeleteIf( PLkrHashTable plkr, LKR_PFnRecordPred pfnPredicate, void* pvState); #endif /* LKR_APPLY_IF */ /* Check table for consistency. Returns 0 if okay, or the number of * errors otherwise. */ IRTL_DLLEXP int LKR_CheckTable( PLkrHashTable plkr); /* Remove all data from the table */ IRTL_DLLEXP void LKR_Clear( PLkrHashTable plkr); /* Number of elements in the table */ IRTL_DLLEXP DWORD LKR_Size( PLkrHashTable plkr); /* Maximum possible number of elements in the table */ IRTL_DLLEXP DWORD LKR_MaxSize( PLkrHashTable plkr); /* Is the hash table usable? */ IRTL_DLLEXP BOOL LKR_IsUsable( PLkrHashTable plkr); /* Is the hash table consistent and correct? */ IRTL_DLLEXP BOOL LKR_IsValid( PLkrHashTable plkr); #ifdef LKR_EXPOSED_TABLE_LOCK /* Lock the table (exclusively) for writing */ IRTL_DLLEXP void LKR_WriteLock( PLkrHashTable plkr); /* Lock the table (possibly shared) for reading */ IRTL_DLLEXP void LKR_ReadLock( PLkrHashTable plkr); /* Unlock the table for writing */ IRTL_DLLEXP void LKR_WriteUnlock( PLkrHashTable plkr); /* Unlock the table for reading */ IRTL_DLLEXP void LKR_ReadUnlock( PLkrHashTable plkr); /* Is the table already locked for writing? */ IRTL_DLLEXP BOOL LKR_IsWriteLocked( PLkrHashTable plkr); /* Is the table already locked for reading? */ IRTL_DLLEXP BOOL LKR_IsReadLocked( PLkrHashTable plkr); /* Is the table unlocked for writing? */ IRTL_DLLEXP BOOL LKR_IsWriteUnlocked( PLkrHashTable plkr); /* Is the table unlocked for reading? */ IRTL_DLLEXP BOOL LKR_IsReadUnlocked( PLkrHashTable plkr); /* Convert the read lock to a write lock. Note: another thread may acquire * exclusive access to the table before this routine returns. */ IRTL_DLLEXP void LKR_ConvertSharedToExclusive( PLkrHashTable plkr); /* Convert the write lock to a read lock */ IRTL_DLLEXP void LKR_ConvertExclusiveToShared( PLkrHashTable plkr); #endif /* LKR_EXPOSED_TABLE_LOCK */ #ifdef __cplusplus } // extern "C" // Only provide iterators in the C++ interface. It's too hard to // provide the correct ownership semantics in a typesafe way in C, // and C users can always use the LKR_ApplyIf family of callback // enumerators if they really need to walk the hashtable. #ifdef LKR_STL_ITERATORS #pragma message("STL iterators") // needed for std::forward_iterator_tag, etc # include #include #define LKR_ITER_TRACE IRTLTRACE class IRTL_DLLEXP LKR_Iterator { private: friend IRTL_DLLEXP LKR_Iterator LKR_Begin(PLkrHashTable plkr); friend IRTL_DLLEXP LKR_Iterator LKR_End(PLkrHashTable plkr); // private ctor LKR_Iterator(bool); public: // default ctor LKR_Iterator(); // copy ctor LKR_Iterator(const LKR_Iterator& rhs); // assignment operator LKR_Iterator& operator=(const LKR_Iterator& rhs); // dtor ~LKR_Iterator(); // Increment the iterator to point to the next record, or to LKR_End() bool Increment(); // Is the iterator valid? bool IsValid() const; // Returns the record that the iterator points to. // Must point to a valid record. const void* Record() const; // Returns the key of the record that the iterator points to. // Must point to a valid record. const DWORD_PTR Key() const; // Compare two iterators for equality bool operator==(const LKR_Iterator& rhs) const; // Compare two iterators for inequality bool operator!=(const LKR_Iterator& rhs) const; // pointer to implementation object void* pImpl; }; // class LKR_Iterator /* Return iterator pointing to first item in table */ IRTL_DLLEXP LKR_Iterator LKR_Begin( PLkrHashTable plkr); /* Return a one-past-the-end iterator. Always empty. */ IRTL_DLLEXP LKR_Iterator LKR_End( PLkrHashTable plkr); /* Insert a record * Returns `true' if successful; iterResult points to that record * Returns `false' otherwise; iterResult == End() */ IRTL_DLLEXP bool LKR_Insert( PLkrHashTable plkr, /* in */ const void* pvRecord, /* out */ LKR_Iterator& riterResult, /* in */ bool fOverwrite=false); /* Erase the record pointed to by the iterator; adjust the iterator * to point to the next record. Returns `true' if successful. */ IRTL_DLLEXP bool LKR_Erase( PLkrHashTable plkr, /* in,out */ LKR_Iterator& riter); /* Erase the records in the range [riterFirst, riterLast). * Returns `true' if successful. */ IRTL_DLLEXP bool LKR_Erase( PLkrHashTable plkr, /*in*/ LKR_Iterator& riterFirst, /*in*/ LKR_Iterator& riterLast); /* Find the (first) record that has its key == pnKey. * If successful, returns `true' and iterator points to (first) record. * If fails, returns `false' and iterator == End() */ IRTL_DLLEXP bool LKR_Find( PLkrHashTable plkr, /* in */ DWORD_PTR pnKey, /* out */ LKR_Iterator& riterResult); /* Find the range of records that have their keys == pnKey. * If successful, returns `true', iterFirst points to first record, * and iterLast points to one-beyond-the last such record. * If fails, returns `false' and both iterators == End(). * Primarily useful when fMultiKeys == TRUE */ IRTL_DLLEXP bool LKR_EqualRange( PLkrHashTable plkr, /* in */ DWORD_PTR pnKey, /* out */ LKR_Iterator& riterFirst, // inclusive /* out */ LKR_Iterator& riterLast); // exclusive #endif // LKR_STL_ITERATORS //-------------------------------------------------------------------- // A typesafe wrapper for PLkrHashTable // // * _Derived must derive from TypedLkrHashTable and provide certain member // functions. It's needed for various downcasting operations. // * _Record is the type of the record. PLkrHashTable will store // pointers to _Record, as const void*. // * _Key is the type of the key. _Key is used directly; i.e., it is // not assumed to be a pointer type. PLkrHashTable assumes that // the key is stored in the associated record. See the comments // at the declaration of LKR_PFnExtractKey for more details. // // You may need to add the following line to your code to disable // warning messages about truncating extremly long identifiers. // #pragma warning (disable : 4786) // // The _Derived class should look something like this: // class CDerived : public TypedLkrHashTable // { // public: // CDerived() // : TypedLkrHashTable("CDerived") // {/*other ctor actions*/} // static KeyType ExtractKey(const RecordType* pTest); // static DWORD CalcKeyHash(const KeyType Key); // static bool EqualKeys(const KeyType Key1, const KeyType Key2); // static void AddRefRecord(RecordType* pRecord,LK_ADDREF_REASON lkar); // // optional: other functions // }; // //-------------------------------------------------------------------- template class TypedLkrHashTable { public: // convenient aliases typedef _Derived Derived; typedef _Record Record; typedef _Key Key; typedef TypedLkrHashTable<_Derived, _Record, _Key> HashTable; #ifdef LKR_APPLY_IF // LKR_ApplyIf() and LKR_DeleteIf(): Does the record match the predicate? // Note: takes a Record*, not a const Record*. You can modify the // record in Pred() or Action(), if you like, but if you do, you // should use LKL_WRITELOCK to lock the table. typedef LK_PREDICATE (WINAPI *PFnRecordPred) (Record* pRec, void* pvState); // Apply() et al: Perform action on record. typedef LK_ACTION (WINAPI *PFnRecordAction)(Record* pRec, void* pvState); #endif // LKR_APPLY_IF protected: PLkrHashTable m_plkr; // Wrappers for the typesafe methods exposed by the derived class static const DWORD_PTR WINAPI _ExtractKey(const void* pvRecord) { const _Record* pRec = static_cast(pvRecord); const _Key key = static_cast(_Derived::ExtractKey(pRec)); // I would prefer to use reinterpret_cast here and in _CalcKeyHash // and _EqualKeys, but the stupid Win64 compiler thinks it knows // better than I do. return (const DWORD_PTR) key; } static DWORD WINAPI _CalcKeyHash(const DWORD_PTR pnKey) { const _Key key = (const _Key) (DWORD_PTR) pnKey; return _Derived::CalcKeyHash(key); } static BOOL WINAPI _EqualKeys(const DWORD_PTR pnKey1, const DWORD_PTR pnKey2) { const _Key key1 = (const _Key) (DWORD_PTR) pnKey1; const _Key key2 = (const _Key) (DWORD_PTR) pnKey2; return _Derived::EqualKeys(key1, key2); } static void WINAPI _AddRefRecord(const void* pvRecord, LK_ADDREF_REASON lkar) { _Record* pRec = static_cast<_Record*>(const_cast(pvRecord)); _Derived::AddRefRecord(pRec, lkar); } #ifdef LKR_APPLY_IF // Typesafe wrappers for Apply, ApplyIf, and DeleteIf. class CState { public: PFnRecordPred m_pfnPred; PFnRecordAction m_pfnAction; void* m_pvState; CState( PFnRecordPred pfnPred, PFnRecordAction pfnAction, void* pvState) : m_pfnPred(pfnPred), m_pfnAction(pfnAction), m_pvState(pvState) {} }; static LK_PREDICATE WINAPI _Pred(const void* pvRecord, void* pvState) { _Record* pRec = static_cast<_Record*>(const_cast(pvRecord)); CState* pState = static_cast(pvState); return (*pState->m_pfnPred)(pRec, pState->m_pvState); } static LK_ACTION WINAPI _Action(const void* pvRecord, void* pvState) { _Record* pRec = static_cast<_Record*>(const_cast(pvRecord)); CState* pState = static_cast(pvState); return (*pState->m_pfnAction)(pRec, pState->m_pvState); } #endif // LKR_APPLY_IF public: TypedLkrHashTable( LPCSTR pszName, // An identifier for debugging LK_TABLESIZE nTableSize, // Small/Med/Large number of elements bool fMultiKeys=false // Allow multiple identical keys? ) : m_plkr(NULL) { m_plkr = LKR_CreateTable(pszName, _ExtractKey, _CalcKeyHash, _EqualKeys, _AddRefRecord, nTableSize, fMultiKeys); } ~TypedLkrHashTable() { LKR_DeleteTable(m_plkr); } LK_RETCODE InsertRecord(const _Record* pRec, bool fOverwrite=false) { return LKR_InsertRecord(m_plkr, pRec, fOverwrite); } LK_RETCODE DeleteKey(const _Key key, bool fDeleteAllSame=false) { const void* pvKey = reinterpret_cast((DWORD_PTR)(key)); DWORD_PTR pnKey = reinterpret_cast(pvKey); return LKR_DeleteKey(m_plkr, pnKey, fDeleteAllSame); } LK_RETCODE DeleteRecord(const _Record* pRec) { return LKR_DeleteRecord(m_plkr, pRec);} // Note: returns a _Record**, not a const Record**. Note that you // can use a const type for the template parameter to ensure constness. LK_RETCODE FindKey(const _Key key, _Record** ppRec) const { if (ppRec == NULL) return LK_BAD_RECORD; *ppRec = NULL; const void* pvRec = NULL; const void* pvKey = reinterpret_cast((DWORD_PTR)(key)); DWORD_PTR pnKey = reinterpret_cast(pvKey); LK_RETCODE lkrc = LKR_FindKey(m_plkr, pnKey, &pvRec); *ppRec = static_cast<_Record*>(const_cast(pvRec)); return lkrc; } LK_RETCODE FindRecord(const _Record* pRec) const { return LKR_FindRecord(m_plkr, pRec);} #ifdef LKR_APPLY_IF DWORD Apply(PFnRecordAction pfnAction, void* pvState=NULL, LK_LOCKTYPE lkl=LKL_READLOCK) { IRTLASSERT(pfnAction != NULL); if (pfnAction == NULL) return 0; CState state(NULL, pfnAction, pvState); return LKR_Apply(m_plkr, _Action, &state, lkl); } DWORD ApplyIf(PFnRecordPred pfnPredicate, PFnRecordAction pfnAction, void* pvState=NULL, LK_LOCKTYPE lkl=LKL_READLOCK) { IRTLASSERT(pfnPredicate != NULL && pfnAction != NULL); if (pfnPredicate == NULL || pfnAction == NULL) return 0; CState state(pfnPredicate, pfnAction, pvState); return LKR_ApplyIf(m_plkr, _Pred, _Action, &state, lkl); } DWORD DeleteIf(PFnRecordPred pfnPredicate, void* pvState=NULL) { IRTLASSERT(pfnPredicate != NULL); if (pfnPredicate == NULL) return 0; CState state(pfnPredicate, NULL, pvState); return LKR_DeleteIf(m_plkr, _Pred, &state); } #endif // LKR_APPLY_IF int CheckTable() const { return LKR_CheckTable(m_plkr); } void Clear() { return LKR_Clear(m_plkr); } DWORD Size() const { return LKR_Size(m_plkr); } DWORD MaxSize() const { return LKR_MaxSize(m_plkr); } BOOL IsUsable() const { return LKR_IsUsable(m_plkr); } BOOL IsValid() const { return LKR_IsValid(m_plkr); } #ifdef LKR_EXPOSED_TABLE_LOCK void WriteLock() { LKR_WriteLock(m_plkr); } void ReadLock() const { LKR_ReadLock(m_plkr); } void WriteUnlock() { LKR_WriteUnlock(m_plkr); } void ReadUnlock() const { LKR_ReadUnlock(m_plkr); } BOOL IsWriteLocked() const { return LKR_IsWriteLocked(m_plkr); } BOOL IsReadLocked() const { return LKR_IsReadLocked(m_plkr); } BOOL IsWriteUnlocked() const { return LKR_IsWriteUnlocked(m_plkr); } BOOL IsReadUnlocked() const { return LKR_IsReadUnlocked(m_plkr); } void ConvertSharedToExclusive() const { LKR_ConvertSharedToExclusive(m_plkr); } void ConvertExclusiveToShared() const { LKR_ConvertExclusiveToShared(m_plkr); } #endif // LKR_EXPOSED_TABLE_LOCK #ifdef LKR_STL_ITERATORS friend class LKR_Iterator; // TODO: const_iterator public: class iterator { friend class TypedLkrHashTable<_Derived, _Record, _Key>; protected: LKR_Iterator m_iter; iterator( LKR_Iterator& rhs) : m_iter(rhs) { LKR_ITER_TRACE(_TEXT("Typed::prot ctor, this=%p, rhs=%p\n"), this, &rhs); } public: typedef std::forward_iterator_tag iterator_category; typedef _Record value_type; typedef ptrdiff_t difference_type; typedef size_t size_type; typedef value_type& reference; typedef value_type* pointer; iterator() : m_iter() { LKR_ITER_TRACE(_TEXT("Typed::default ctor, this=%p\n"), this); } iterator( const iterator& rhs) : m_iter(rhs.m_iter) { LKR_ITER_TRACE(_TEXT("Typed::copy ctor, this=%p, rhs=%p\n"), this, &rhs); } iterator& operator=( const iterator& rhs) { LKR_ITER_TRACE(_TEXT("Typed::operator=, this=%p, rhs=%p\n"), this, &rhs); m_iter = rhs.m_iter; return *this; } ~iterator() { LKR_ITER_TRACE(_TEXT("Typed::dtor, this=%p\n"), this); } reference operator*() const { void* pvRecord = const_cast(m_iter.Record()); return reinterpret_cast(pvRecord); } pointer operator->() const { return &(operator*()); } // pre-increment iterator& operator++() { LKR_ITER_TRACE(_TEXT("Typed::pre-increment, this=%p\n"), this); m_iter.Increment(); return *this; } // post-increment iterator operator++(int) { LKR_ITER_TRACE(_TEXT("Typed::post-increment, this=%p\n"), this); iterator iterPrev = *this; m_iter.Increment(); return iterPrev; } bool operator==( const iterator& rhs) const { LKR_ITER_TRACE(_TEXT("Typed::operator==, this=%p, rhs=%p\n"), this, &rhs); return m_iter == rhs.m_iter; } bool operator!=( const iterator& rhs) const { LKR_ITER_TRACE(_TEXT("Typed::operator!=, this=%p, rhs=%p\n"), this, &rhs); return m_iter != rhs.m_iter; } _Record* Record() const { LKR_ITER_TRACE(_TEXT("Typed::Record, this=%p\n"), this); return reinterpret_cast<_Record*>( const_cast(m_iter.Record())); } _Key Key() const { LKR_ITER_TRACE(_TEXT("Typed::Key, this=%p\n"), this); return reinterpret_cast<_Key>( reinterpret_cast(m_iter.Key())); } }; // class iterator // Return iterator pointing to first item in table iterator begin() { LKR_ITER_TRACE(_TEXT("Typed::begin()\n")); return LKR_Begin(m_plkr); } // Return a one-past-the-end iterator. Always empty. iterator end() const { LKR_ITER_TRACE(_TEXT("Typed::end()\n")); return LKR_End(m_plkr); } template TypedLkrHashTable( LPCSTR pszName, // An identifier for debugging _InputIterator f, // first element in range _InputIterator l, // one-beyond-last element LK_TABLESIZE nTableSize, // Small/Med/Large number of elements bool fMultiKeys=false // Allow multiple identical keys? ) { m_plkr = LKR_CreateTable(pszName, _ExtractKey, _CalcKeyHash, _EqualKeys, _AddRefRecord, nTableSize, fMultiKeys); insert(f, l); } template void insert(_InputIterator f, _InputIterator l) { for ( ; f != l; ++f) InsertRecord(&(*f)); } bool Insert( const _Record* pRecord, iterator& riterResult, bool fOverwrite=false) { LKR_ITER_TRACE(_TEXT("Typed::Insert\n")); return LKR_Insert(m_plkr, pRecord, riterResult.m_iter, fOverwrite); } bool Erase( iterator& riter) { LKR_ITER_TRACE(_TEXT("Typed::Erase\n")); return LKR_Erase(m_plkr, riter.m_iter); } bool Erase( iterator& riterFirst, iterator& riterLast) { LKR_ITER_TRACE(_TEXT("Typed::Erase2\n")); return LKR_Erase(m_plkr, riterFirst.m_iter, riterLast.m_iter); } bool Find( const _Key key, iterator& riterResult) { LKR_ITER_TRACE(_TEXT("Typed::Find\n")); const void* pvKey = reinterpret_cast((DWORD_PTR)(key)); DWORD_PTR pnKey = reinterpret_cast(pvKey); return LKR_Find(m_plkr, pnKey, riterResult.m_iter); } bool EqualRange( const _Key key, iterator& riterFirst, iterator& riterLast) { LKR_ITER_TRACE(_TEXT("Typed::EqualRange\n")); const void* pvKey = reinterpret_cast((DWORD_PTR)(key)); DWORD_PTR pnKey = reinterpret_cast(pvKey); return LKR_EqualRange(m_plkr, pnKey, riterFirst.m_iter, riterLast.m_iter); } #undef LKR_ITER_TRACE #endif // LKR_STL_ITERATORS }; // class TypedLkrHashTable #endif /* __cplusplus */ #endif /* __LKR_HASH_H__ */