xpcom/ds/nsHashtable.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   5  * This Original Code has been modified by IBM Corporation.
   6  * Modifications made by IBM described herein are
   7  * Copyright (c) International Business Machines
   8  * Corporation, 2000
   9  *
  10  * Modifications to Mozilla code or documentation
  11  * identified per MPL Section 3.3
  12  *
  13  * Date         Modified by     Description of modification
  14  * 04/20/2000   IBM Corp.       Added PR_CALLBACK for Optlink use in OS2
  15  */
  16
  17 /**
  18  * nsHashtable is OBSOLETE. Use nsTHashtable or a derivative instead.
  19  */
  20
  21 #ifndef nsHashtable_h__
  22 #define nsHashtable_h__
  23
  24 #include "pldhash.h"
  25 #include "nscore.h"
  26 #include "nsISupports.h"
  27 #include "nsTraceRefcnt.h"
  28 #include "nsStringFwd.h"
  29
  30 class nsIObjectInputStream;
  31 class nsIObjectOutputStream;
  32
  33 struct PRLock;
  34
  35 class nsHashKey {
  36   protected:
  37     nsHashKey(void) {
  38 #ifdef DEBUG
  39         mKeyType = UnknownKey;
  40 #endif
  41         MOZ_COUNT_CTOR(nsHashKey);
  42     }
  43
  44
  45   public:
  46     // Virtual destructor because all hash keys are |delete|d via a
  47     // nsHashKey pointer.
  48
  49     virtual ~nsHashKey(void);
  50     virtual uint32_t HashCode(void) const = 0;
  51     virtual bool Equals(const nsHashKey *aKey) const = 0;
  52     virtual nsHashKey *Clone() const = 0;
  53     virtual nsresult Write(nsIObjectOutputStream* aStream) const;
  54
  55 #ifdef DEBUG
  56   public:
  57     // used for verification that we're casting to the correct key type
  58     enum nsHashKeyType {
  59         UnknownKey,
  60         SupportsKey,
  61         PRUint32Key,
  62         VoidKey,
  63         IDKey,
  64         CStringKey,
  65         StringKey
  66     };
  67     nsHashKeyType GetKeyType() const { return mKeyType; }
  68   protected:
  69     nsHashKeyType mKeyType;
  70 #endif
  71 };
  72
  73 // Enumerator and Read/Write callback functions.
  74
  75 // Return values for nsHashtableEnumFunc
  76 enum {
  77     kHashEnumerateStop      = false,
  78     kHashEnumerateNext      = true
  79 };
  80
  81 typedef bool
  82 (* nsHashtableEnumFunc)(nsHashKey *aKey, void *aData, void* aClosure);
  83
  84 typedef nsresult
  85 (* nsHashtableReadEntryFunc)(nsIObjectInputStream *aStream, nsHashKey **aKey,
  86                              void **aData);
  87
  88 // NB: may be called with null aKey or aData, to free just one of the two.
  89 typedef void
  90 (* nsHashtableFreeEntryFunc)(nsIObjectInputStream *aStream, nsHashKey *aKey,
  91                              void *aData);
  92
  93 typedef nsresult
  94 (* nsHashtableWriteDataFunc)(nsIObjectOutputStream *aStream, void *aData);
  95
  96 class nsHashtable {
  97   protected:
  98     // members
  99     PRLock*         mLock;
 100     PLDHashTable    mHashtable;
 101     bool            mEnumerating;
 102
 103   public:
 104     nsHashtable(uint32_t aSize = 16, bool threadSafe = false);
 105     virtual ~nsHashtable();
 106
 107     int32_t Count(void) { return mHashtable.entryCount; }
 108     bool Exists(nsHashKey *aKey);
 109     void *Put(nsHashKey *aKey, void *aData);
 110     void *Get(nsHashKey *aKey);
 111     void *Remove(nsHashKey *aKey);
 112     nsHashtable *Clone();
 113     void Enumerate(nsHashtableEnumFunc aEnumFunc, void* aClosure = nullptr);
 114     void Reset();
 115     void Reset(nsHashtableEnumFunc destroyFunc, void* aClosure = nullptr);
 116
 117     nsHashtable(nsIObjectInputStream* aStream,
 118                 nsHashtableReadEntryFunc aReadEntryFunc,
 119                 nsHashtableFreeEntryFunc aFreeEntryFunc,
 120                 nsresult *aRetVal);
 121     nsresult Write(nsIObjectOutputStream* aStream,
 122                    nsHashtableWriteDataFunc aWriteDataFunc) const;
 123 };
 124
 125 ////////////////////////////////////////////////////////////////////////////////
 126 // nsObjectHashtable: an nsHashtable where the elements are C++ objects to be
 127 // deleted
 128
 129 typedef void* (* nsHashtableCloneElementFunc)(nsHashKey *aKey, void *aData, void* aClosure);
 130
 131 class nsObjectHashtable : public nsHashtable {
 132   public:
 133     nsObjectHashtable(nsHashtableCloneElementFunc cloneElementFun,
 134                       void* cloneElementClosure,
 135                       nsHashtableEnumFunc destroyElementFun,
 136                       void* destroyElementClosure,
 137                       uint32_t aSize = 16, bool threadSafe = false);
 138     ~nsObjectHashtable();
 139
 140     nsHashtable *Clone();
 141     void Reset();
 142     bool RemoveAndDelete(nsHashKey *aKey);
 143
 144   protected:
 145     static PLDHashOperator CopyElement(PLDHashTable* table,
 146                                        PLDHashEntryHdr* hdr,
 147                                        uint32_t i, void *arg);
 148
 149     nsHashtableCloneElementFunc mCloneElementFun;
 150     void*                       mCloneElementClosure;
 151     nsHashtableEnumFunc         mDestroyElementFun;
 152     void*                       mDestroyElementClosure;
 153 };
 154
 155 ////////////////////////////////////////////////////////////////////////////////
 156 // nsSupportsHashtable: an nsHashtable where the elements are nsISupports*
 157
 158 class nsSupportsHashtable
 159   : private nsHashtable
 160 {
 161   public:
 162     nsSupportsHashtable(uint32_t aSize = 16, bool threadSafe = false)
 163       : nsHashtable(aSize, threadSafe) {}
 164     ~nsSupportsHashtable();
 165
 166     int32_t Count(void) {
 167         return nsHashtable::Count();
 168     }
 169     bool Exists(nsHashKey *aKey) {
 170         return nsHashtable::Exists (aKey);
 171     }
 172     bool Put(nsHashKey *aKey,
 173                nsISupports *aData,
 174                nsISupports **value = nullptr);
 175     nsISupports* Get(nsHashKey *aKey);
 176     bool Remove(nsHashKey *aKey, nsISupports **value = nullptr);
 177     nsHashtable *Clone();
 178     void Enumerate(nsHashtableEnumFunc aEnumFunc, void* aClosure = nullptr) {
 179         nsHashtable::Enumerate(aEnumFunc, aClosure);
 180     }
 181     void Reset();
 182
 183   private:
 184     static bool ReleaseElement(nsHashKey *, void *, void *);
 185     static PLDHashOperator EnumerateCopy(PLDHashTable*,
 186                                          PLDHashEntryHdr* hdr,
 187                                          uint32_t i, void *arg);
 188 };
 189
 190 ////////////////////////////////////////////////////////////////////////////////
 191 // nsISupportsKey: Where keys are nsISupports objects that get refcounted.
 192
 193 class nsISupportsKey : public nsHashKey {
 194   protected:
 195     nsISupports* mKey;
 196
 197   public:
 198     nsISupportsKey(const nsISupportsKey& aKey) : mKey(aKey.mKey) {
 199 #ifdef DEBUG
 200         mKeyType = SupportsKey;
 201 #endif
 202         NS_IF_ADDREF(mKey);
 203     }
 204
 205     nsISupportsKey(nsISupports* key) {
 206 #ifdef DEBUG
 207         mKeyType = SupportsKey;
 208 #endif
 209         mKey = key;
 210         NS_IF_ADDREF(mKey);
 211     }
 212
 213     ~nsISupportsKey(void) {
 214         NS_IF_RELEASE(mKey);
 215     }
 216
 217     uint32_t HashCode(void) const {
 218         return NS_PTR_TO_INT32(mKey);
 219     }
 220
 221     bool Equals(const nsHashKey *aKey) const {
 222         NS_ASSERTION(aKey->GetKeyType() == SupportsKey, "mismatched key types");
 223         return (mKey == ((nsISupportsKey *) aKey)->mKey);
 224     }
 225
 226     nsHashKey *Clone() const {
 227         return new nsISupportsKey(mKey);
 228     }
 229
 230     nsISupportsKey(nsIObjectInputStream* aStream, nsresult *aResult);
 231     nsresult Write(nsIObjectOutputStream* aStream) const;
 232
 233     nsISupports* GetValue() { return mKey; }
 234 };
 235
 236
 237 class nsPRUint32Key : public nsHashKey {
 238 protected:
 239     uint32_t mKey;
 240 public:
 241     nsPRUint32Key(uint32_t key) {
 242 #ifdef DEBUG
 243         mKeyType = PRUint32Key;
 244 #endif
 245         mKey = key;
 246     }
 247
 248     uint32_t HashCode(void) const {
 249         return mKey;
 250     }
 251
 252     bool Equals(const nsHashKey *aKey) const {
 253         return mKey == ((const nsPRUint32Key *) aKey)->mKey;
 254     }
 255     nsHashKey *Clone() const {
 256         return new nsPRUint32Key(mKey);
 257     }
 258     uint32_t GetValue() { return mKey; }
 259 };
 260
 261 ////////////////////////////////////////////////////////////////////////////////
 262 // nsVoidKey: Where keys are void* objects that don't get refcounted.
 263
 264 class nsVoidKey : public nsHashKey {
 265   protected:
 266     void* mKey;
 267
 268   public:
 269     nsVoidKey(const nsVoidKey& aKey) : mKey(aKey.mKey) {
 270 #ifdef DEBUG
 271         mKeyType = aKey.mKeyType;
 272 #endif
 273     }
 274
 275     nsVoidKey(void* key) {
 276 #ifdef DEBUG
 277         mKeyType = VoidKey;
 278 #endif
 279         mKey = key;
 280     }
 281
 282     uint32_t HashCode(void) const {
 283         return NS_PTR_TO_INT32(mKey);
 284     }
 285
 286     bool Equals(const nsHashKey *aKey) const {
 287         NS_ASSERTION(aKey->GetKeyType() == VoidKey, "mismatched key types");
 288         return (mKey == ((const nsVoidKey *) aKey)->mKey);
 289     }
 290
 291     nsHashKey *Clone() const {
 292         return new nsVoidKey(mKey);
 293     }
 294
 295     void* GetValue() { return mKey; }
 296 };
 297
 298 // for null-terminated c-strings
 299 class nsCStringKey : public nsHashKey {
 300   public:
 301
 302     // NB: when serializing, NEVER_OWN keys are deserialized as OWN.
 303     enum Ownership {
 304         NEVER_OWN,  // very long lived, even clones don't need to copy it.
 305         OWN_CLONE,  // as long lived as this key. But clones make a copy.
 306         OWN         // to be free'd in key dtor. Clones make their own copy.
 307     };
 308
 309     nsCStringKey(const nsCStringKey& aStrKey);
 310     nsCStringKey(const char* str, int32_t strLen = -1, Ownership own = OWN_CLONE);
 311     nsCStringKey(const nsAFlatCString& str);
 312     nsCStringKey(const nsACString& str);
 313     ~nsCStringKey(void);
 314
 315     uint32_t HashCode(void) const;
 316     bool Equals(const nsHashKey* aKey) const;
 317     nsHashKey* Clone() const;
 318     nsCStringKey(nsIObjectInputStream* aStream, nsresult *aResult);
 319     nsresult Write(nsIObjectOutputStream* aStream) const;
 320
 321     // For when the owner of the hashtable wants to peek at the actual
 322     // string in the key. No copy is made, so be careful.
 323     const char* GetString() const { return mStr; }
 324     uint32_t GetStringLength() const { return mStrLen; }
 325
 326   protected:
 327     char*       mStr;
 328     uint32_t    mStrLen;
 329     Ownership   mOwnership;
 330 };
 331
 332 // for null-terminated unicode strings
 333 class nsStringKey : public nsHashKey {
 334   public:
 335
 336     // NB: when serializing, NEVER_OWN keys are deserialized as OWN.
 337     enum Ownership {
 338         NEVER_OWN,  // very long lived, even clones don't need to copy it.
 339         OWN_CLONE,  // as long lived as this key. But clones make a copy.
 340         OWN         // to be free'd in key dtor. Clones make their own copy.
 341     };
 342
 343     nsStringKey(const nsStringKey& aKey);
 344     nsStringKey(const PRUnichar* str, int32_t strLen = -1, Ownership own = OWN_CLONE);
 345     nsStringKey(const nsAFlatString& str);
 346     nsStringKey(const nsAString& str);
 347     ~nsStringKey(void);
 348
 349     uint32_t HashCode(void) const;
 350     bool Equals(const nsHashKey* aKey) const;
 351     nsHashKey* Clone() const;
 352     nsStringKey(nsIObjectInputStream* aStream, nsresult *aResult);
 353     nsresult Write(nsIObjectOutputStream* aStream) const;
 354
 355     // For when the owner of the hashtable wants to peek at the actual
 356     // string in the key. No copy is made, so be careful.
 357     const PRUnichar* GetString() const { return mStr; }
 358     uint32_t GetStringLength() const { return mStrLen; }
 359
 360   protected:
 361     PRUnichar*  mStr;
 362     uint32_t    mStrLen;
 363     Ownership   mOwnership;
 364 };
 365
 366 ////////////////////////////////////////////////////////////////////////////////
 367
 368 #endif // nsHashtable_h__