1CMPH - C Minimal Perfect Hashing Library 2 3 4------------------------------------------------------------------- 5 6 7 Motivation 8 ========== 9 10A perfect hash function maps a static set of n keys into a set of m integer numbers without collisions, where m is greater than or equal to n. If m is equal to n, the function is called minimal. 11 12Minimal perfect hash functions (concepts.html) are widely used for memory efficient storage and fast retrieval of items from static sets, such as words in natural languages, reserved words in programming languages or interactive systems, universal resource locations (URLs) in Web search engines, or item sets in data mining techniques. Therefore, there are applications for minimal perfect hash functions in information retrieval systems, database systems, language translation systems, electronic commerce systems, compilers, operating systems, among others. 13 14The use of minimal perfect hash functions is, until now, restricted to scenarios where the set of keys being hashed is small, because of the limitations of current algorithms. But in many cases, to deal with huge set of keys is crucial. So, this project gives to the free software community an API that will work with sets in the order of billion of keys. 15 16Probably, the most interesting application for minimal perfect hash functions is its use as an indexing structure for databases. The most popular data structure used as an indexing structure in databases is the B+ tree. In fact, the B+ tree is very used for dynamic applications with frequent insertions and deletions of records. However, for applications with sporadic modifications and a huge number of queries the B+ tree is not the best option, because practical deployments of this structure are extremely complex, and perform poorly with very large sets of keys such as those required for the new frontiers database applications (http://acmqueue.com/modules.php?name=Content&pa=showpage&pid=299). 17 18For example, in the information retrieval field, the work with huge collections is a daily task. The simple assignment of ids to web pages of a collection can be a challenging task. While traditional databases simply cannot handle more traffic once the working set of web page urls does not fit in main memory anymore, minimal perfect hash functions can easily scale to hundred of millions of entries, using stock hardware. 19 20As there are lots of applications for minimal perfect hash functions, it is important to implement memory and time efficient algorithms for constructing such functions. The lack of similar libraries in the free software world has been the main motivation to create the C Minimal Perfect Hashing Library (gperf is a bit different (gperf.html), since it was conceived to create very fast perfect hash functions for small sets of keys and CMPH Library was conceived to create minimal perfect hash functions for very large sets of keys). C Minimal Perfect Hashing Library is a portable LGPLed library to generate and to work with very efficient minimal perfect hash functions. 21 22------------------------------------------------------------------- 23 24 25 Description 26 =========== 27 28The CMPH Library encapsulates the newest and more efficient algorithms in an easy-to-use, production-quality, fast API. The library was designed to work with big entries that cannot fit in the main memory. It has been used successfully for constructing minimal perfect hash functions for sets with more than 100 million of keys, and we intend to expand this number to the order of billion of keys. Although there is a lack of similar libraries, we can point out some of the distinguishable features of the CMPH Library: 29 30- Fast. 31- Space-efficient with main memory usage carefully documented. 32- The best modern algorithms are available (or at least scheduled for implementation :-)). 33- Works with in-disk key sets through of using the adapter pattern. 34- Serialization of hash functions. 35- Portable C code (currently works on GNU/Linux and WIN32 and is reported to work in OpenBSD and Solaris). 36- Object oriented implementation. 37- Easily extensible. 38- Well encapsulated API aiming binary compatibility through releases. 39- Free Software. 40 41---------------------------------------- 42 43 44 Supported Algorithms 45 ==================== 46 47- CHD Algorithm: 48 - It is the fastest algorithm to build PHFs and MPHFs in linear time. 49 - It generates the most compact PHFs and MPHFs we know of. 50 - It can generate PHFs with a load factor up to 99 %. 51 - It can be used to generate t-perfect hash functions. A t-perfect hash function allows at most t collisions in a given bin. It is a well-known fact that modern memories are organized as blocks which constitute transfer unit. Example of such blocks are cache lines for internal memory or sectors for hard disks. Thus, it can be very useful for devices that carry out I/O operations in blocks. 52 - It is a two level scheme. It uses a first level hash function to split the key set in buckets of average size determined by a parameter b in the range [1,32]. In the second level it uses displacement values to resolve the collisions that have given rise to the buckets. 53 - It can generate MPHFs that can be stored in approximately 2.07 bits per key. 54 - For a load factor equal to the maximum one that is achieved by the BDZ algorithm (81 %), the resulting PHFs are stored in approximately 1.40 bits per key. 55- BDZ Algorithm: 56 - It is very simple and efficient. It outperforms all the ones below. 57 - It constructs both PHFs and MPHFs in linear time. 58 - The maximum load factor one can achieve for a PHF is 1/1.23. 59 - It is based on acyclic random 3-graphs. A 3-graph is a generalization of a graph where each edge connects 3 vertices instead of only 2. 60 - The resulting MPHFs are not order preserving. 61 - The resulting MPHFs can be stored in only (2 + x)cn bits, where c should be larger than or equal to 1.23 and x is a constant larger than 0 (actually, x = 1/b and b is a parameter that should be larger than 2). For c = 1.23 and b = 8, the resulting functions are stored in approximately 2.6 bits per key. 62 - For its maximum load factor (81 %), the resulting PHFs are stored in approximately 1.95 bits per key. 63- BMZ Algorithm: 64 - Construct MPHFs in linear time. 65 - It is based on cyclic random graphs. This makes it faster than the CHM algorithm. 66 - The resulting MPHFs are not order preserving. 67 - The resulting MPHFs are more compact than the ones generated by the CHM algorithm and can be stored in 4cn bytes, where c is in the range [0.93,1.15]. 68- BRZ Algorithm: 69 - A very fast external memory based algorithm for constructing minimal perfect hash functions for sets in the order of billions of keys. 70 - It works in linear time. 71 - The resulting MPHFs are not order preserving. 72 - The resulting MPHFs can be stored using less than 8.0 bits per key. 73- CHM Algorithm: 74 - Construct minimal MPHFs in linear time. 75 - It is based on acyclic random graphs 76 - The resulting MPHFs are order preserving. 77 - The resulting MPHFs are stored in 4cn bytes, where c is greater than 2. 78- FCH Algorithm: 79 - Construct minimal perfect hash functions that require less than 4 bits per key to be stored. 80 - The resulting MPHFs are very compact and very efficient at evaluation time 81 - The algorithm is only efficient for small sets. 82 - It is used as internal algorithm in the BRZ algorithm to efficiently solve larger problems and even so to generate MPHFs that require approximately 4.1 bits per key to be stored. For that, you just need to set the parameters -a to brz and -c to a value larger than or equal to 2.6. 83 84---------------------------------------- 85 86 87 News for version 2.0 88 ==================== 89 90Cleaned up most warnings for the c code. 91 92Experimental C++ interface (--enable-cxxmph) implementing the BDZ algorithm in 93a convenient SimpleMPHIndex interface, which serves as the basis 94for drop-in replacements for std::unordered_map, sparsehash::sparse_hash_map 95and sparsehash::dense_hash_map. Faster lookup time at the expense of insertion 96time. See cxxmpph/mph_map.h and cxxmph/mph_index.h for details. 97 98 99 News for version 1.1 100 ==================== 101 102Fixed a bug in the chd_pc algorithm and reorganized tests. 103 104 105 News for version 1.0 106 ==================== 107 108This is a bugfix only version, after which a revamp of the cmph code and 109algorithms will be done. 110 111 112 News for version 0.9 113 ==================== 114 115- The CHD algorithm (chd.html), which is an algorithm that can be tuned to generate MPHFs that require approximately 2.07 bits per key to be stored. The algorithm outperforms the BDZ algorithm (bdz.html) and therefore is the fastest one available in the literature for sets that can be treated in internal memory. 116- The CHD_PH algorithm (chd.html), which is an algorithm to generate PHFs with load factor up to 99 %. It is actually the CHD algorithm without the ranking step. If we set the load factor to 81 %, which is the maximum that can be obtained with the BDZ algorithm (bdz.html), the resulting functions can be stored in 1.40 bits per key. The space requirement increases with the load factor. 117- All reported bugs and suggestions have been corrected and included as well. 118 119 120 News for version 0.8 121 ==================== 122 123- An algorithm to generate MPHFs that require around 2.6 bits per key to be stored (bdz.html), which is referred to as BDZ algorithm. The algorithm is the fastest one available in the literature for sets that can be treated in internal memory. 124- An algorithm to generate PHFs with range m = cn, for c > 1.22 (bdz.html), which is referred to as BDZ_PH algorithm. It is actually the BDZ algorithm without the ranking step. The resulting functions can be stored in 1.95 bits per key for c = 1.23 and are considerably faster than the MPHFs generated by the BDZ algorithm. 125- An adapter to support a vector of struct as the source of keys has been added. 126- An API to support the ability of packing a perfect hash function into a preallocated contiguous memory space. The computation of a packed function is still faster and can be easily mmapped. 127- The hash functions djb2, fnv and sdbm were removed because they do not use random seeds and therefore are not useful for MPHFs algorithms. 128- All reported bugs and suggestions have been corrected and included as well. 129 130News log (newslog.html) 131 132---------------------------------------- 133 134 135 Examples 136 ======== 137 138Using cmph is quite simple. Take a look. 139 140 #include <cmph.h> 141 #include <string.h> 142 // Create minimal perfect hash function from in-memory vector 143 int main(int argc, char **argv) 144 { 145 146 // Creating a filled vector 147 unsigned int i = 0; 148 const char *vector[] = {"aaaaaaaaaa", "bbbbbbbbbb", "cccccccccc", "dddddddddd", "eeeeeeeeee", 149 "ffffffffff", "gggggggggg", "hhhhhhhhhh", "iiiiiiiiii", "jjjjjjjjjj"}; 150 unsigned int nkeys = 10; 151 FILE* mphf_fd = fopen("temp.mph", "w"); 152 // Source of keys 153 cmph_io_adapter_t *source = cmph_io_vector_adapter((char **)vector, nkeys); 154 155 //Create minimal perfect hash function using the brz algorithm. 156 cmph_config_t *config = cmph_config_new(source); 157 cmph_config_set_algo(config, CMPH_BRZ); 158 cmph_config_set_mphf_fd(config, mphf_fd); 159 cmph_t *hash = cmph_new(config); 160 cmph_config_destroy(config); 161 cmph_dump(hash, mphf_fd); 162 cmph_destroy(hash); 163 fclose(mphf_fd); 164 165 //Find key 166 mphf_fd = fopen("temp.mph", "r"); 167 hash = cmph_load(mphf_fd); 168 while (i < nkeys) { 169 const char *key = vector[i]; 170 unsigned int id = cmph_search(hash, key, (cmph_uint32)strlen(key)); 171 fprintf(stderr, "key:%s -- hash:%u\n", key, id); 172 i++; 173 } 174 175 //Destroy hash 176 cmph_destroy(hash); 177 cmph_io_vector_adapter_destroy(source); 178 fclose(mphf_fd); 179 return 0; 180 } 181 182Download vector_adapter_ex1.c (examples/vector_adapter_ex1.c). This example does not work in versions below 0.6. You need to update the sources from GIT to make it work. 183 184------------------------------- 185 186 #include <cmph.h> 187 #include <stdio.h> 188 #include <string.h> 189 // Create minimal perfect hash function from in-disk keys using BDZ algorithm 190 int main(int argc, char **argv) 191 { 192 //Open file with newline separated list of keys 193 FILE * keys_fd = fopen("keys.txt", "r"); 194 cmph_t *hash = NULL; 195 if (keys_fd == NULL) 196 { 197 fprintf(stderr, "File \"keys.txt\" not found\n"); 198 exit(1); 199 } 200 // Source of keys 201 cmph_io_adapter_t *source = cmph_io_nlfile_adapter(keys_fd); 202 203 cmph_config_t *config = cmph_config_new(source); 204 cmph_config_set_algo(config, CMPH_BDZ); 205 hash = cmph_new(config); 206 cmph_config_destroy(config); 207 208 //Find key 209 const char *key = "jjjjjjjjjj"; 210 unsigned int id = cmph_search(hash, key, (cmph_uint32)strlen(key)); 211 fprintf(stderr, "Id:%u\n", id); 212 //Destroy hash 213 cmph_destroy(hash); 214 cmph_io_nlfile_adapter_destroy(source); 215 fclose(keys_fd); 216 return 0; 217 } 218 219Download file_adapter_ex2.c (examples/file_adapter_ex2.c) and keys.txt (examples/keys.txt). This example does not work in versions below 0.8. You need to update the sources from GIT to make it work. 220 221Click here to see more examples (examples.html) 222 223-------------------------------------- 224 225 226 The cmph application 227 ==================== 228 229cmph is the name of both the library and the utility 230application that comes with this package. You can use the cmph 231application for constructing minimal perfect hash functions from the command line. 232The cmph utility 233comes with a number of flags, but it is very simple to create and to query 234minimal perfect hash functions: 235 236 $ # Using the chm algorithm (default one) for constructing a mphf for keys in file keys_file 237 $ ./cmph -g keys_file 238 $ # Query id of keys in the file keys_query 239 $ ./cmph -m keys_file.mph keys_query 240 241The additional options let you set most of the parameters you have 242available through the C API. Below you can see the full help message for the 243utility. 244 245 usage: cmph [-v] [-h] [-V] [-k nkeys] [-f hash_function] [-g [-c algorithm_dependent_value][-s seed] ] 246 [-a algorithm] [-M memory_in_MB] [-b algorithm_dependent_value] [-t keys_per_bin] [-d tmp_dir] 247 [-m file.mph] keysfile 248 Minimum perfect hashing tool 249 250 -h print this help message 251 -c c value determines: 252 * the number of vertices in the graph for the algorithms BMZ and CHM 253 * the number of bits per key required in the FCH algorithm 254 * the load factor in the CHD_PH algorithm 255 -a algorithm - valid values are 256 * bmz 257 * bmz8 258 * chm 259 * brz 260 * fch 261 * bdz 262 * bdz_ph 263 * chd_ph 264 * chd 265 -f hash function (may be used multiple times) - valid values are 266 * jenkins 267 -V print version number and exit 268 -v increase verbosity (may be used multiple times) 269 -k number of keys 270 -g generation mode 271 -s random seed 272 -m minimum perfect hash function file 273 -M main memory availability (in MB) used in BRZ algorithm 274 -d temporary directory used in BRZ algorithm 275 -b the meaning of this parameter depends on the algorithm selected in the -a option: 276 * For BRZ it is used to make the maximal number of keys in a bucket lower than 256. 277 In this case its value should be an integer in the range [64,175]. Default is 128. 278 279 * For BDZ it is used to determine the size of some precomputed rank 280 information and its value should be an integer in the range [3,10]. Default 281 is 7. The larger is this value, the more compact are the resulting functions 282 and the slower are them at evaluation time. 283 284 * For CHD and CHD_PH it is used to set the average number of keys per bucket 285 and its value should be an integer in the range [1,32]. Default is 4. The 286 larger is this value, the slower is the construction of the functions. 287 This parameter has no effect for other algorithms. 288 289 -t set the number of keys per bin for a t-perfect hashing function. A t-perfect 290 hash function allows at most t collisions in a given bin. This parameter applies 291 only to the CHD and CHD_PH algorithms. Its value should be an integer in the 292 range [1,128]. Defaul is 1 293 keysfile line separated file with keys 294 295 296 Additional Documentation 297 ======================== 298 299FAQ (faq.html) 300 301 302 Downloads 303 ========= 304 305Use the project page at sourceforge: http://sf.net/projects/cmph 306 307 308 License Stuff 309 ============= 310 311Code is under the LGPL and the MPL 1.1. 312 313---------------------------------------- 314 315Enjoy! 316 317Davi de Castro Reis (davi@users.sourceforge.net) 318 319Djamel Belazzougui (db8192@users.sourceforge.net) 320 321Fabiano Cupertino Botelho (fc_botelho@users.sourceforge.net) 322 323Nivio Ziviani (nivio@dcc.ufmg.br) 324 325Last Updated: Sun Jun 3 04:09:55 2012 326 327