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