xpcom/ds/nsHashtable.h

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