hashtb.h

Go to the documentation of this file.
00001 /**
00002  * @file ccn/hashtb.h
00003  * 
00004  * Hash table.
00005  *
00006  * Part of the CCNx C Library.
00007  *
00008  * Copyright (C) 2008, 2009 Palo Alto Research Center, Inc.
00009  *
00010  * This library is free software; you can redistribute it and/or modify it
00011  * under the terms of the GNU Lesser General Public License version 2.1
00012  * as published by the Free Software Foundation.
00013  * This library is distributed in the hope that it will be useful,
00014  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00015  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
00016  * Lesser General Public License for more details. You should have received
00017  * a copy of the GNU Lesser General Public License along with this library;
00018  * if not, write to the Free Software Foundation, Inc., 51 Franklin Street,
00019  * Fifth Floor, Boston, MA 02110-1301 USA.
00020  */
00021 
00022 #ifndef CCN_HASHTB_DEFINED
00023 #define CCN_HASHTB_DEFINED
00024 
00025 #include <stddef.h>
00026 
00027 struct hashtb; /* details are private to the implementation */
00028 struct hashtb_enumerator; /* more about this below */
00029 typedef void (*hashtb_finalize_proc)(struct hashtb_enumerator *);
00030 struct hashtb_param {
00031     hashtb_finalize_proc finalize; /* default is NULL */
00032     void *finalize_data;           /* default is NULL */
00033     int orders;                    /* default is 0 */
00034 }; 
00035 
00036 /*
00037  * hashtb_create: Create a new hash table.
00038  * The param may be NULL to use the defaults, otherwise
00039  * a copy of *param is made.
00040  */
00041 struct hashtb *
00042 hashtb_create(size_t item_size, const struct hashtb_param *param);
00043 
00044 /*
00045  * hashtb_get_param: Get the parameters used when creating ht.
00046  * Return value is the finalize_data; param may be NULL if no
00047  * other parameters are needed.
00048  */
00049 void *
00050 hashtb_get_param(struct hashtb *ht, struct hashtb_param *param);
00051 
00052 /*
00053  * hashtb_destroy: Destroy a hash table and all of its elements.
00054  */
00055 void
00056 hashtb_destroy(struct hashtb **ht);
00057 
00058 /*
00059  * hashtb_n: Get current number of elements.
00060  */
00061 int
00062 hashtb_n(struct hashtb *ht);
00063 
00064 /*
00065  * hashtb_lookup: Find an item
00066  * Keys are arbitrary data of specified length.
00067  * Returns NULL if not found, or a pointer to the item's data.
00068  */
00069 void *
00070 hashtb_lookup(struct hashtb *ht, const void *key, size_t keysize);
00071 
00072 /* The client owns the memory for an enumerator, normally in a local. */ 
00073 struct hashtb_enumerator {
00074     struct hashtb *ht;
00075     const void *key;        /* Key concatenated with extension data */
00076     size_t keysize;
00077     size_t extsize;
00078     void *data;
00079     size_t datasize;
00080     void *priv[3];
00081 };
00082 
00083 /*
00084  * hashtb_start: initializes enumerator to first table entry
00085  * Order of enumeration is arbitrary.
00086  * Must do this before using the enumerator for anything else,
00087  * and must call hashtb_end when done.
00088  * Returns second argument.
00089  */
00090 struct hashtb_enumerator *
00091 hashtb_start(struct hashtb *, struct hashtb_enumerator *);
00092 void hashtb_end(struct hashtb_enumerator *);
00093 
00094 void hashtb_next(struct hashtb_enumerator *);
00095 
00096 /*
00097  * hashtb_seek: Find or add an item
00098  * For a newly added item, the keysize bytes of key along
00099  * with the extsize following bytes get copied into the
00100  * hash table's data.  If the key is really a null-terminated
00101  * string, consider using extsize = 1 to copy the terminator
00102  * into the keystore.  This feature may also be used to copy
00103  * larger chunks of unvarying data that are meant to be kept with key.
00104  *
00105  * returns 0 if entry existed before, 1 if newly added,
00106  *        -1 for a fatal error (ENOMEM or key==NULL).
00107  */
00108 int
00109 hashtb_seek(struct hashtb_enumerator *hte,
00110             const void *key, size_t keysize, size_t extsize);
00111 #define HT_OLD_ENTRY 0
00112 #define HT_NEW_ENTRY 1
00113 
00114 /*
00115  * hashtb_delete: Delete an item
00116  * The item will be unlinked from the table, and will
00117  * be freed when safe to do so (i.e., when there are no other
00118  * active enumerators).  The finalize proc (if any) will be
00119  * called before the item is freed, and it is responsible for
00120  * cleaning up any external pointers to the item.
00121  * When the delete returns, the enumerator will be positioned
00122  * at the next item.
00123  */
00124 void hashtb_delete(struct hashtb_enumerator *);
00125 
00126 /*
00127  * hashtb_rehash: Hint about number of buckets to use
00128  * Normally the implementation grows the number of buckets as needed.
00129  * This optional call might help if the caller knows something about
00130  * the expected number of elements in advance, or if the size of the
00131  * table has shrunken dramatically and is not expected to grow soon.
00132  * Does nothing if there are any active enumerators.
00133  */
00134 void hashtb_rehash(struct hashtb *ht, unsigned n_buckets);
00135 
00136 #endif
Generated on Fri May 13 16:27:02 2011 for Content-Centric Networking in C by  doxygen 1.6.3