mozilla

Compare Revisions

Detailed XPCOM hashtable guide

Change Revisions

Revision 64403:

Revision 64403 by BenjaminSmedberg on

Revision 64404:

Revision 64404 by Dmpotter on

Title:
Detailed XPCOM hashtable guide
Detailed XPCOM hashtable guide
Slug:
Detailed_XPCOM_hashtable_guide
Detailed_XPCOM_hashtable_guide
Tags:
XPCOM, NeedsMarkupWork
XPCOM, NeedsMarkupWork
Content:

Revision 64403
Revision 64404
n276      The <code>PLDHash</code> implementation is a fairly low-levn276      The <code>PLDHash</code> implementation is a fairly low-lev
>el implementation, written in C. It is extremely flexible, but re>el implementation, written in C. It is extremely flexible, but re
>quires some time to understand and use. A basic guide is included>quires some time to understand and use. A basic guide is included
> here, but you should read most of {{template.Source("xpcom/ds/pl> here, but you should read most of {{template.Source("xpcom/glue/
>dhash.h")}} if you intend to use <code>PLDHash</code>. The C++ wr>pldhash.h")}} if you intend to use <code>PLDHash</code>. The C++ 
>appers for <code>PLDHash</code> (see below) are often much easier>wrappers for <code>PLDHash</code> (see below) are often much easi
> and safer to use in C++ code, as many potential casting errors a>er and safer to use in C++ code, as many potential casting errors
>re easily avoided.> are easily avoided.
277    </p>
278    <p>277    </p>
278    <p>
279      You must declare an <b>entry struct</b> type, deriving from279      You must declare an <b>entry struct</b> type, deriving from
> {{wiki.template('Named-source', [ "xpcom/ds/pldhash.h#88", "&lt;> {{wiki.template('Named-source', [ "xpcom/glue/pldhash.h#81", "&l
>code&gt;PLDHashEntryHdr&lt;/code&gt;" ])}}. This entry struct sho>t;code&gt;PLDHashEntryHdr&lt;/code&gt;" ])}}. This entry struct s
>uld contain whatever data you wish to store in the hashtable (any>hould contain whatever data you wish to store in the hashtable (a
> pointer or fixed-length data type). <b>Note:</b> because of the >ny pointer or fixed-length data type). <b>Note:</b> because of th
>double-hashing implementation, entries may move in memory when th>e double-hashing implementation, entries may move in memory when 
>e hashtable is altered. If you need entry pointers to remain cons>the hashtable is altered. If you need entry pointers to remain co
>tant, you may want to consider using <code><a href="#PLHashTable">nstant, you may want to consider using <code><a href="#PLHashTabl
>>PLHashTable</a></code> instead.>e">PLHashTable</a></code> instead.
280    </p>
281    <p>280    </p>
281    <p>
282      You must also initialize a {{wiki.template('Named-source', 282      You must also initialize a {{wiki.template('Named-source', 
>[ "xpcom/ds/pldhash.h#330", "&lt;code&gt;PLDHashTableOps&lt;/code>[ "xpcom/glue/pldhash.h#312", "&lt;code&gt;PLDHashTableOps&lt;/co
>&gt;" ])}} structure. This serves similarly to a vtable in C++, w>de&gt;" ])}} structure. This serves similarly to a vtable in C++,
>ith pointers to appropriate user-defined functions that initializ> with pointers to appropriate user-defined functions that initial
>e, compare, and match entries. Because <code>PLDHash</code> does >ize, compare, and match entries. Because <code>PLDHash</code> doe
>not know what datatype your key is, all functions that work with >s not know what datatype your key is, all functions that work wit
>keys are declared using <code>{{wiki.template('Named-source', [ ">h keys are declared using <code>{{wiki.template('Named-source', [
>xpcom/ds/pldhash.h#82", "const void*" ])}}</code>, and your clien> "xpcom/glue/pldhash.h#354", "const void*" ])}}</code>, and your 
>t code must cast these pointers to the appropriate type.>client code must cast these pointers to the appropriate type.
n288      <li>When allocated on the stack, or as a C++ class member, n288      <li>When allocated on the stack, or as a C++ class member, 
>the table must be initialized using <code>{{wiki.template('Named->the table must be initialized using <code>{{wiki.template('Named-
>source', [ "xpcom/ds/pldhash.h#417", "PL_DHashTableInit" ])}}</co>source', [ "xpcom/glue/pldhash.h#427", "PL_DHashTableInit" ])}}</
>de>, and finalized using <code>{{wiki.template('Named-source', [ >code>, and finalized using <code>{{wiki.template('Named-source', 
>"xpcom/ds/pldhash.h#449", "PL_DHashTableFinish" ])}}</code>;>[ "xpcom/glue/pldhash.h#459", "PL_DHashTableFinish" ])}}</code>;
n290      <li>When allocated on the heap, use <code>{{wiki.template('n290      <li>When allocated on the heap, use <code>{{wiki.template('
>Named-source', [ "xpcom/ds/pldhash.h#400", "PL_NewDHashTable" ])}>Named-source', [ "xpcom/glue/pldhash.h#410", "PL_NewDHashTable" ]
>}</code> and <code>{{wiki.template('Named-source', [ "xpcom/ds/pl>)}}</code> and <code>{{wiki.template('Named-source', [ "xpcom/glu
>dhash.h#408", "PL_DHashTableDestroy" ])}}</code> to allocate and >e/pldhash.h#420", "PL_DHashTableDestroy" ])}}</code> to allocate 
>delete the table.>and delete the table.
n312      <code>nsTHashtable</code> is a C++ template that wraps <codn312      <code>nsTHashtable</code> is a C++ template that wraps <cod
>e>PLDHash</code>. It hides many of the complexities of <code>PLDH>e>PLDHash</code>. It hides many of the complexities of <code>PLDH
>ash</code> (callback functions, the ops structure, etc). You shou>ash</code> (callback functions, the ops structure, etc). You shou
>ld read {{template.Source("xpcom/ds/nsTHashtable.h")}}.>ld read {{template.Source("xpcom/glue/nsTHashtable.h")}}.
313    </p>
314    <p>313    </p>
314    <p>
315      To use <code>nsTHashtable</code>, you must declare an entry315      To use <code>nsTHashtable</code>, you must declare an entry
>-class in a {{wiki.template('Named-source', [ "xpcom/ds/nsTHashta>-class in a {{wiki.template('Named-source', [ "xpcom/glue/nsTHash
>ble.h#65", "pre-defined format" ])}}. This entry class contains t>table.h#65", "pre-defined format" ])}}. This entry class contains
>he key and the data that you are hashing (just like <code>PLDHash> the key and the data that you are hashing (just like <code>PLDHa
></code>, above). It also declares functions that manipulate the k>sh</code>, above). It also declares functions that manipulate the
>ey. In most cases, the functions of this entry class can be entir> key. In most cases, the functions of this entry class can be ent
>ely inline. For examples of entry classes, see the declarations a>irely inline. For examples of entry classes, see the declarations
>t {{template.Source("xpcom/ds/nsHashKeys.h")}}.> at {{template.Source("xpcom/glue/nsHashKeys.h")}}.
n364      The important files to read are {{template.Source("xpcom/dsn364      The important files to read are {{template.Source("xpcom/gl
>/nsBaseHashtable.h")}} and {{template.Source("xpcom/ds/nsHashKeys>ue/nsBaseHashtable.h")}} and {{template.Source("xpcom/glue/nsHash
>.h")}}. These classes can be used on the stack, as a class member>Keys.h")}}. These classes can be used on the stack, as a class me
>, or on the heap. Initialize using the <code>Init()</code> functi>mber, or on the heap. Initialize using the <code>Init()</code> fu
>on; you can specify whether you need thread-safety at this time. >nction; you can specify whether you need thread-safety at this ti
>Use the <code>Put()</code>, <code>Get()</code>, and <code>Remove(>me. Use the <code>Put()</code>, <code>Get()</code>, and <code>Rem
>)</code> methods to alter the table.>ove()</code> methods to alter the table.
n406            cast using <code>{{wiki.template('Named-source', [ "xn406            cast using <code>{{wiki.template('Named-source', [ "x
>pcom/base/nscore.h#316", "NS_PTR_TO_INT32" ])}}</code>>pcom/base/nscore.h#443", "NS_PTR_TO_INT32" ])}}</code>
n427            <code>{{wiki.template('Named-source', [ "string/src/nn427            <code>{{wiki.template('Named-source', [ "xpcom/glue/n
>sReadableUtils.cpp#1105", "HashString()" ])}}</code>>sTHashtable.cpp#41", "HashString()" ])}}</code>
n440            <code>{{wiki.template('Named-source', [ "xpcom/ds/nsHn440            <code>{{wiki.template('Named-source', [ "xpcom/glue/n
>ashKeys.h#207", "nsIDHashKey::HashKey()" ])}}</code>>sHashKeys.h#227", "nsIDHashKey::HashKey()" ])}}</code>
n461      <code>{{wiki.template('Named-source', [ "xpcom/ds/nsHashtabn461      <code>{{wiki.template('Named-source', [ "xpcom/ds/nsHashtab
>le.h#143", "nsObjectHashtable" ])}}</code> is a form of <code>nsH>le.h#163", "nsObjectHashtable" ])}}</code> is a form of <code>nsH
>ashtable</code>. It has been replaced by <code>nsClassHashtable</>ashtable</code>. It has been replaced by <code>nsClassHashtable</
>code>.>code>.
t467      <code>{{wiki.template('Named-source', [ "xpcom/ds/nsHashtabt467      <code>{{wiki.template('Named-source', [ "xpcom/ds/nsHashtab
>le.h#173", "nsSupportsHashtable" ])}}</code> is a form of <code>n>le.h#193", "nsSupportsHashtable" ])}}</code> is a form of <code>n
>sHashtable</code>. It has been replaced by <code>nsInterfaceHasht>sHashtable</code>. It has been replaced by <code>nsInterfaceHasht
>able</code>.>able</code>.

Back to History