1 /************************************************************************************************* 2 * The hash database API of Tokyo Cabinet 3 * Copyright (C) 2006-2012 FAL Labs 4 * This file is part of Tokyo Cabinet. 5 * Tokyo Cabinet is free software; you can redistribute it and/or modify it under the terms of 6 * the GNU Lesser General Public License as published by the Free Software Foundation; either 7 * version 2.1 of the License or any later version. Tokyo Cabinet is distributed in the hope 8 * that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of 9 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public 10 * License for more details. 11 * You should have received a copy of the GNU Lesser General Public License along with Tokyo 12 * Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, 13 * Boston, MA 02111-1307 USA. 14 *************************************************************************************************/ 15 16 17 #ifndef _TCHDB_H /* duplication check */ 18 #define _TCHDB_H 19 20 #if defined(__cplusplus) 21 #define __TCHDB_CLINKAGEBEGIN extern "C" { 22 #define __TCHDB_CLINKAGEEND } 23 #else 24 #define __TCHDB_CLINKAGEBEGIN 25 #define __TCHDB_CLINKAGEEND 26 #endif 27 __TCHDB_CLINKAGEBEGIN 28 29 30 #include <tcutil.h> 31 32 33 34 /************************************************************************************************* 35 * API 36 *************************************************************************************************/ 37 38 39 typedef struct { /* type of structure for a hash database */ 40 void *mmtx; /* mutex for method */ 41 void *rmtxs; /* mutexes for records */ 42 void *dmtx; /* mutex for the while database */ 43 void *wmtx; /* mutex for write ahead logging */ 44 void *eckey; /* key for thread specific error code */ 45 char *rpath; /* real path for locking */ 46 uint8_t type; /* database type */ 47 uint8_t flags; /* additional flags */ 48 uint64_t bnum; /* number of the bucket array */ 49 uint8_t apow; /* power of record alignment */ 50 uint8_t fpow; /* power of free block pool number */ 51 uint8_t opts; /* options */ 52 char *path; /* path of the database file */ 53 int fd; /* file descriptor of the database file */ 54 uint32_t omode; /* open mode */ 55 uint64_t rnum; /* number of the records */ 56 uint64_t fsiz; /* size of the database file */ 57 uint64_t frec; /* offset of the first record */ 58 uint64_t dfcur; /* offset of the cursor for defragmentation */ 59 uint64_t iter; /* offset of the iterator */ 60 char *map; /* pointer to the mapped memory */ 61 uint64_t msiz; /* size of the mapped memory */ 62 uint64_t xmsiz; /* size of the extra mapped memory */ 63 uint64_t xfsiz; /* extra size of the file for mapped memory */ 64 uint32_t *ba32; /* 32-bit bucket array */ 65 uint64_t *ba64; /* 64-bit bucket array */ 66 uint32_t align; /* record alignment */ 67 uint32_t runit; /* record reading unit */ 68 bool zmode; /* whether compression is used */ 69 int32_t fbpmax; /* maximum number of the free block pool */ 70 void *fbpool; /* free block pool */ 71 int32_t fbpnum; /* number of the free block pool */ 72 int32_t fbpmis; /* number of missing retrieval of the free block pool */ 73 bool async; /* whether asynchronous storing is called */ 74 TCXSTR *drpool; /* delayed record pool */ 75 TCXSTR *drpdef; /* deferred records of the delayed record pool */ 76 uint64_t drpoff; /* offset of the delayed record pool */ 77 TCMDB *recc; /* cache for records */ 78 uint32_t rcnum; /* maximum number of cached records */ 79 TCCODEC enc; /* pointer to the encoding function */ 80 void *encop; /* opaque object for the encoding functions */ 81 TCCODEC dec; /* pointer to the decoding function */ 82 void *decop; /* opaque object for the decoding functions */ 83 int ecode; /* last happened error code */ 84 bool fatal; /* whether a fatal error occured */ 85 uint64_t inode; /* inode number */ 86 time_t mtime; /* modification time */ 87 uint32_t dfunit; /* unit step number of auto defragmentation */ 88 uint32_t dfcnt; /* counter of auto defragmentation */ 89 bool tran; /* whether in the transaction */ 90 int walfd; /* file descriptor of write ahead logging */ 91 uint64_t walend; /* end offset of write ahead logging */ 92 int dbgfd; /* file descriptor for debugging */ 93 volatile int64_t cnt_writerec; /* tesing counter for record write times */ 94 volatile int64_t cnt_reuserec; /* tesing counter for record reuse times */ 95 volatile int64_t cnt_moverec; /* tesing counter for record move times */ 96 volatile int64_t cnt_readrec; /* tesing counter for record read times */ 97 volatile int64_t cnt_searchfbp; /* tesing counter for FBP search times */ 98 volatile int64_t cnt_insertfbp; /* tesing counter for FBP insert times */ 99 volatile int64_t cnt_splicefbp; /* tesing counter for FBP splice times */ 100 volatile int64_t cnt_dividefbp; /* tesing counter for FBP divide times */ 101 volatile int64_t cnt_mergefbp; /* tesing counter for FBP merge times */ 102 volatile int64_t cnt_reducefbp; /* tesing counter for FBP reduce times */ 103 volatile int64_t cnt_appenddrp; /* tesing counter for DRP append times */ 104 volatile int64_t cnt_deferdrp; /* tesing counter for DRP defer times */ 105 volatile int64_t cnt_flushdrp; /* tesing counter for DRP flush times */ 106 volatile int64_t cnt_adjrecc; /* tesing counter for record cache adjust times */ 107 volatile int64_t cnt_defrag; /* tesing counter for defragmentation times */ 108 volatile int64_t cnt_shiftrec; /* tesing counter for record shift times */ 109 volatile int64_t cnt_trunc; /* tesing counter for truncation times */ 110 } TCHDB; 111 112 enum { /* enumeration for additional flags */ 113 HDBFOPEN = 1 << 0, /* whether opened */ 114 HDBFFATAL = 1 << 1 /* whether with fatal error */ 115 }; 116 117 enum { /* enumeration for tuning options */ 118 HDBTLARGE = 1 << 0, /* use 64-bit bucket array */ 119 HDBTDEFLATE = 1 << 1, /* compress each record with Deflate */ 120 HDBTBZIP = 1 << 2, /* compress each record with BZIP2 */ 121 HDBTTCBS = 1 << 3, /* compress each record with TCBS */ 122 HDBTEXCODEC = 1 << 4 /* compress each record with custom functions */ 123 }; 124 125 enum { /* enumeration for open modes */ 126 HDBOREADER = 1 << 0, /* open as a reader */ 127 HDBOWRITER = 1 << 1, /* open as a writer */ 128 HDBOCREAT = 1 << 2, /* writer creating */ 129 HDBOTRUNC = 1 << 3, /* writer truncating */ 130 HDBONOLCK = 1 << 4, /* open without locking */ 131 HDBOLCKNB = 1 << 5, /* lock without blocking */ 132 HDBOTSYNC = 1 << 6 /* synchronize every transaction */ 133 }; 134 135 136 /* Get the message string corresponding to an error code. 137 `ecode' specifies the error code. 138 The return value is the message string of the error code. */ 139 const char *tchdberrmsg(int ecode); 140 141 142 /* Create a hash database object. 143 The return value is the new hash database object. */ 144 TCHDB *tchdbnew(void); 145 146 147 /* Delete a hash database object. 148 `hdb' specifies the hash database object. 149 If the database is not closed, it is closed implicitly. Note that the deleted object and its 150 derivatives can not be used anymore. */ 151 void tchdbdel(TCHDB *hdb); 152 153 154 /* Get the last happened error code of a hash database object. 155 `hdb' specifies the hash database object. 156 The return value is the last happened error code. 157 The following error codes are defined: `TCESUCCESS' for success, `TCETHREAD' for threading 158 error, `TCEINVALID' for invalid operation, `TCENOFILE' for file not found, `TCENOPERM' for no 159 permission, `TCEMETA' for invalid meta data, `TCERHEAD' for invalid record header, `TCEOPEN' 160 for open error, `TCECLOSE' for close error, `TCETRUNC' for trunc error, `TCESYNC' for sync 161 error, `TCESTAT' for stat error, `TCESEEK' for seek error, `TCEREAD' for read error, 162 `TCEWRITE' for write error, `TCEMMAP' for mmap error, `TCELOCK' for lock error, `TCEUNLINK' 163 for unlink error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir error, `TCERMDIR' for 164 rmdir error, `TCEKEEP' for existing record, `TCENOREC' for no record found, and `TCEMISC' for 165 miscellaneous error. */ 166 int tchdbecode(TCHDB *hdb); 167 168 169 /* Set mutual exclusion control of a hash database object for threading. 170 `hdb' specifies the hash database object which is not opened. 171 If successful, the return value is true, else, it is false. 172 Note that the mutual exclusion control is needed if the object is shared by plural threads and 173 this function should be called before the database is opened. */ 174 bool tchdbsetmutex(TCHDB *hdb); 175 176 177 /* Set the tuning parameters of a hash database object. 178 `hdb' specifies the hash database object which is not opened. 179 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 180 default value is specified. The default value is 131071. Suggested size of the bucket array 181 is about from 0.5 to 4 times of the number of all records to be stored. 182 `apow' specifies the size of record alignment by power of 2. If it is negative, the default 183 value is specified. The default value is 4 standing for 2^4=16. 184 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 185 is negative, the default value is specified. The default value is 10 standing for 2^10=1024. 186 `opts' specifies options by bitwise-or: `HDBTLARGE' specifies that the size of the database 187 can be larger than 2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies that each record 188 is compressed with Deflate encoding, `HDBTBZIP' specifies that each record is compressed with 189 BZIP2 encoding, `HDBTTCBS' specifies that each record is compressed with TCBS encoding. 190 If successful, the return value is true, else, it is false. 191 Note that the tuning parameters should be set before the database is opened. */ 192 bool tchdbtune(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 193 194 195 /* Set the caching parameters of a hash database object. 196 `hdb' specifies the hash database object which is not opened. 197 `rcnum' specifies the maximum number of records to be cached. If it is not more than 0, the 198 record cache is disabled. It is disabled by default. 199 If successful, the return value is true, else, it is false. 200 Note that the caching parameters should be set before the database is opened. */ 201 bool tchdbsetcache(TCHDB *hdb, int32_t rcnum); 202 203 204 /* Set the size of the extra mapped memory of a hash database object. 205 `hdb' specifies the hash database object which is not opened. 206 `xmsiz' specifies the size of the extra mapped memory. If it is not more than 0, the extra 207 mapped memory is disabled. The default size is 67108864. 208 If successful, the return value is true, else, it is false. 209 Note that the mapping parameters should be set before the database is opened. */ 210 bool tchdbsetxmsiz(TCHDB *hdb, int64_t xmsiz); 211 212 213 /* Set the unit step number of auto defragmentation of a hash database object. 214 `hdb' specifies the hash database object which is not opened. 215 `dfunit' specifie the unit step number. If it is not more than 0, the auto defragmentation 216 is disabled. It is disabled by default. 217 If successful, the return value is true, else, it is false. 218 Note that the defragmentation parameters should be set before the database is opened. */ 219 bool tchdbsetdfunit(TCHDB *hdb, int32_t dfunit); 220 221 222 /* Open a database file and connect a hash database object. 223 `hdb' specifies the hash database object which is not opened. 224 `path' specifies the path of the database file. 225 `omode' specifies the connection mode: `HDBOWRITER' as a writer, `HDBOREADER' as a reader. 226 If the mode is `HDBOWRITER', the following may be added by bitwise-or: `HDBOCREAT', which 227 means it creates a new database if not exist, `HDBOTRUNC', which means it creates a new 228 database regardless if one exists, `HDBOTSYNC', which means every transaction synchronizes 229 updated contents with the device. Both of `HDBOREADER' and `HDBOWRITER' can be added to by 230 bitwise-or: `HDBONOLCK', which means it opens the database file without file locking, or 231 `HDBOLCKNB', which means locking is performed without blocking. 232 If successful, the return value is true, else, it is false. */ 233 bool tchdbopen(TCHDB *hdb, const char *path, int omode); 234 235 236 /* Close a hash database object. 237 `hdb' specifies the hash database object. 238 If successful, the return value is true, else, it is false. 239 Update of a database is assured to be written when the database is closed. If a writer opens 240 a database but does not close it appropriately, the database will be broken. */ 241 bool tchdbclose(TCHDB *hdb); 242 243 244 /* Store a record into a hash database object. 245 `hdb' specifies the hash database object connected as a writer. 246 `kbuf' specifies the pointer to the region of the key. 247 `ksiz' specifies the size of the region of the key. 248 `vbuf' specifies the pointer to the region of the value. 249 `vsiz' specifies the size of the region of the value. 250 If successful, the return value is true, else, it is false. 251 If a record with the same key exists in the database, it is overwritten. */ 252 bool tchdbput(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 253 254 255 /* Store a string record into a hash database object. 256 `hdb' specifies the hash database object connected as a writer. 257 `kstr' specifies the string of the key. 258 `vstr' specifies the string of the value. 259 If successful, the return value is true, else, it is false. 260 If a record with the same key exists in the database, it is overwritten. */ 261 bool tchdbput2(TCHDB *hdb, const char *kstr, const char *vstr); 262 263 264 /* Store a new record into a hash database object. 265 `hdb' specifies the hash database object connected as a writer. 266 `kbuf' specifies the pointer to the region of the key. 267 `ksiz' specifies the size of the region of the key. 268 `vbuf' specifies the pointer to the region of the value. 269 `vsiz' specifies the size of the region of the value. 270 If successful, the return value is true, else, it is false. 271 If a record with the same key exists in the database, this function has no effect. */ 272 bool tchdbputkeep(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 273 274 275 /* Store a new string record into a hash database object. 276 `hdb' specifies the hash database object connected as a writer. 277 `kstr' specifies the string of the key. 278 `vstr' specifies the string of the value. 279 If successful, the return value is true, else, it is false. 280 If a record with the same key exists in the database, this function has no effect. */ 281 bool tchdbputkeep2(TCHDB *hdb, const char *kstr, const char *vstr); 282 283 284 /* Concatenate a value at the end of the existing record in a hash database object. 285 `hdb' specifies the hash database object connected as a writer. 286 `kbuf' specifies the pointer to the region of the key. 287 `ksiz' specifies the size of the region of the key. 288 `vbuf' specifies the pointer to the region of the value. 289 `vsiz' specifies the size of the region of the value. 290 If successful, the return value is true, else, it is false. 291 If there is no corresponding record, a new record is created. */ 292 bool tchdbputcat(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 293 294 295 /* Concatenate a string value at the end of the existing record in a hash database object. 296 `hdb' specifies the hash database object connected as a writer. 297 `kstr' specifies the string of the key. 298 `vstr' specifies the string of the value. 299 If successful, the return value is true, else, it is false. 300 If there is no corresponding record, a new record is created. */ 301 bool tchdbputcat2(TCHDB *hdb, const char *kstr, const char *vstr); 302 303 304 /* Store a record into a hash database object in asynchronous fashion. 305 `hdb' specifies the hash database object connected as a writer. 306 `kbuf' specifies the pointer to the region of the key. 307 `ksiz' specifies the size of the region of the key. 308 `vbuf' specifies the pointer to the region of the value. 309 `vsiz' specifies the size of the region of the value. 310 If successful, the return value is true, else, it is false. 311 If a record with the same key exists in the database, it is overwritten. Records passed to 312 this function are accumulated into the inner buffer and wrote into the file at a blast. */ 313 bool tchdbputasync(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz); 314 315 316 /* Store a string record into a hash database object in asynchronous fashion. 317 `hdb' specifies the hash database object connected as a writer. 318 `kstr' specifies the string of the key. 319 `vstr' specifies the string of the value. 320 If successful, the return value is true, else, it is false. 321 If a record with the same key exists in the database, it is overwritten. Records passed to 322 this function are accumulated into the inner buffer and wrote into the file at a blast. */ 323 bool tchdbputasync2(TCHDB *hdb, const char *kstr, const char *vstr); 324 325 326 /* Remove a record of a hash database object. 327 `hdb' specifies the hash database object connected as a writer. 328 `kbuf' specifies the pointer to the region of the key. 329 `ksiz' specifies the size of the region of the key. 330 If successful, the return value is true, else, it is false. */ 331 bool tchdbout(TCHDB *hdb, const void *kbuf, int ksiz); 332 333 334 /* Remove a string record of a hash database object. 335 `hdb' specifies the hash database object connected as a writer. 336 `kstr' specifies the string of the key. 337 If successful, the return value is true, else, it is false. */ 338 bool tchdbout2(TCHDB *hdb, const char *kstr); 339 340 341 /* Retrieve a record in a hash database object. 342 `hdb' specifies the hash database object. 343 `kbuf' specifies the pointer to the region of the key. 344 `ksiz' specifies the size of the region of the key. 345 `sp' specifies the pointer to the variable into which the size of the region of the return 346 value is assigned. 347 If successful, the return value is the pointer to the region of the value of the corresponding 348 record. `NULL' is returned if no record corresponds. 349 Because an additional zero code is appended at the end of the region of the return value, 350 the return value can be treated as a character string. Because the region of the return 351 value is allocated with the `malloc' call, it should be released with the `free' call when 352 it is no longer in use. */ 353 void *tchdbget(TCHDB *hdb, const void *kbuf, int ksiz, int *sp); 354 355 356 /* Retrieve a string record in a hash database object. 357 `hdb' specifies the hash database object. 358 `kstr' specifies the string of the key. 359 If successful, the return value is the string of the value of the corresponding record. 360 `NULL' is returned if no record corresponds. 361 Because the region of the return value is allocated with the `malloc' call, it should be 362 released with the `free' call when it is no longer in use. */ 363 char *tchdbget2(TCHDB *hdb, const char *kstr); 364 365 366 /* Retrieve a record in a hash database object and write the value into a buffer. 367 `hdb' specifies the hash database object. 368 `kbuf' specifies the pointer to the region of the key. 369 `ksiz' specifies the size of the region of the key. 370 `vbuf' specifies the pointer to the buffer into which the value of the corresponding record is 371 written. 372 `max' specifies the size of the buffer. 373 If successful, the return value is the size of the written data, else, it is -1. -1 is 374 returned if no record corresponds to the specified key. 375 Note that an additional zero code is not appended at the end of the region of the writing 376 buffer. */ 377 int tchdbget3(TCHDB *hdb, const void *kbuf, int ksiz, void *vbuf, int max); 378 379 380 /* Get the size of the value of a record in a hash database object. 381 `hdb' specifies the hash database object. 382 `kbuf' specifies the pointer to the region of the key. 383 `ksiz' specifies the size of the region of the key. 384 If successful, the return value is the size of the value of the corresponding record, else, 385 it is -1. */ 386 int tchdbvsiz(TCHDB *hdb, const void *kbuf, int ksiz); 387 388 389 /* Get the size of the value of a string record in a hash database object. 390 `hdb' specifies the hash database object. 391 `kstr' specifies the string of the key. 392 If successful, the return value is the size of the value of the corresponding record, else, 393 it is -1. */ 394 int tchdbvsiz2(TCHDB *hdb, const char *kstr); 395 396 397 /* Initialize the iterator of a hash database object. 398 `hdb' specifies the hash database object. 399 If successful, the return value is true, else, it is false. 400 The iterator is used in order to access the key of every record stored in a database. */ 401 bool tchdbiterinit(TCHDB *hdb); 402 403 404 /* Get the next key of the iterator of a hash database object. 405 `hdb' specifies the hash database object. 406 `sp' specifies the pointer to the variable into which the size of the region of the return 407 value is assigned. 408 If successful, the return value is the pointer to the region of the next key, else, it is 409 `NULL'. `NULL' is returned when no record is to be get out of the iterator. 410 Because an additional zero code is appended at the end of the region of the return value, the 411 return value can be treated as a character string. Because the region of the return value is 412 allocated with the `malloc' call, it should be released with the `free' call when it is no 413 longer in use. It is possible to access every record by iteration of calling this function. 414 It is allowed to update or remove records whose keys are fetched while the iteration. 415 However, it is not assured if updating the database is occurred while the iteration. Besides, 416 the order of this traversal access method is arbitrary, so it is not assured that the order of 417 storing matches the one of the traversal access. */ 418 void *tchdbiternext(TCHDB *hdb, int *sp); 419 420 421 /* Get the next key string of the iterator of a hash database object. 422 `hdb' specifies the hash database object. 423 If successful, the return value is the string of the next key, else, it is `NULL'. `NULL' is 424 returned when no record is to be get out of the iterator. 425 Because the region of the return value is allocated with the `malloc' call, it should be 426 released with the `free' call when it is no longer in use. It is possible to access every 427 record by iteration of calling this function. However, it is not assured if updating the 428 database is occurred while the iteration. Besides, the order of this traversal access method 429 is arbitrary, so it is not assured that the order of storing matches the one of the traversal 430 access. */ 431 char *tchdbiternext2(TCHDB *hdb); 432 433 434 /* Get the next extensible objects of the iterator of a hash database object. 435 `hdb' specifies the hash database object. 436 `kxstr' specifies the object into which the next key is wrote down. 437 `vxstr' specifies the object into which the next value is wrote down. 438 If successful, the return value is true, else, it is false. False is returned when no record 439 is to be get out of the iterator. */ 440 bool tchdbiternext3(TCHDB *hdb, TCXSTR *kxstr, TCXSTR *vxstr); 441 442 443 /* Get forward matching keys in a hash database object. 444 `hdb' specifies the hash database object. 445 `pbuf' specifies the pointer to the region of the prefix. 446 `psiz' specifies the size of the region of the prefix. 447 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 448 specified. 449 The return value is a list object of the corresponding keys. This function does never fail. 450 It returns an empty list even if no key corresponds. 451 Because the object of the return value is created with the function `tclistnew', it should be 452 deleted with the function `tclistdel' when it is no longer in use. Note that this function 453 may be very slow because every key in the database is scanned. */ 454 TCLIST *tchdbfwmkeys(TCHDB *hdb, const void *pbuf, int psiz, int max); 455 456 457 /* Get forward matching string keys in a hash database object. 458 `hdb' specifies the hash database object. 459 `pstr' specifies the string of the prefix. 460 `max' specifies the maximum number of keys to be fetched. If it is negative, no limit is 461 specified. 462 The return value is a list object of the corresponding keys. This function does never fail. 463 It returns an empty list even if no key corresponds. 464 Because the object of the return value is created with the function `tclistnew', it should be 465 deleted with the function `tclistdel' when it is no longer in use. Note that this function 466 may be very slow because every key in the database is scanned. */ 467 TCLIST *tchdbfwmkeys2(TCHDB *hdb, const char *pstr, int max); 468 469 470 /* Add an integer to a record in a hash database object. 471 `hdb' specifies the hash database object connected as a writer. 472 `kbuf' specifies the pointer to the region of the key. 473 `ksiz' specifies the size of the region of the key. 474 `num' specifies the additional value. 475 If successful, the return value is the summation value, else, it is `INT_MIN'. 476 If the corresponding record exists, the value is treated as an integer and is added to. If no 477 record corresponds, a new record of the additional value is stored. */ 478 int tchdbaddint(TCHDB *hdb, const void *kbuf, int ksiz, int num); 479 480 481 /* Add a real number to a record in a hash database object. 482 `hdb' specifies the hash database object connected as a writer. 483 `kbuf' specifies the pointer to the region of the key. 484 `ksiz' specifies the size of the region of the key. 485 `num' specifies the additional value. 486 If successful, the return value is the summation value, else, it is Not-a-Number. 487 If the corresponding record exists, the value is treated as a real number and is added to. If 488 no record corresponds, a new record of the additional value is stored. */ 489 double tchdbadddouble(TCHDB *hdb, const void *kbuf, int ksiz, double num); 490 491 492 /* Synchronize updated contents of a hash database object with the file and the device. 493 `hdb' specifies the hash database object connected as a writer. 494 If successful, the return value is true, else, it is false. 495 This function is useful when another process connects to the same database file. */ 496 bool tchdbsync(TCHDB *hdb); 497 498 499 /* Optimize the file of a hash database object. 500 `hdb' specifies the hash database object connected as a writer. 501 `bnum' specifies the number of elements of the bucket array. If it is not more than 0, the 502 default value is specified. The default value is two times of the number of records. 503 `apow' specifies the size of record alignment by power of 2. If it is negative, the current 504 setting is not changed. 505 `fpow' specifies the maximum number of elements of the free block pool by power of 2. If it 506 is negative, the current setting is not changed. 507 `opts' specifies options by bitwise-or: `HDBTLARGE' specifies that the size of the database 508 can be larger than 2GB by using 64-bit bucket array, `HDBTDEFLATE' specifies that each record 509 is compressed with Deflate encoding, `HDBTBZIP' specifies that each record is compressed with 510 BZIP2 encoding, `HDBTTCBS' specifies that each record is compressed with TCBS encoding. If it 511 is `UINT8_MAX', the current setting is not changed. 512 If successful, the return value is true, else, it is false. 513 This function is useful to reduce the size of the database file with data fragmentation by 514 successive updating. */ 515 bool tchdboptimize(TCHDB *hdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts); 516 517 518 /* Remove all records of a hash database object. 519 `hdb' specifies the hash database object connected as a writer. 520 If successful, the return value is true, else, it is false. */ 521 bool tchdbvanish(TCHDB *hdb); 522 523 524 /* Copy the database file of a hash database object. 525 `hdb' specifies the hash database object. 526 `path' specifies the path of the destination file. If it begins with `@', the trailing 527 substring is executed as a command line. 528 If successful, the return value is true, else, it is false. False is returned if the executed 529 command returns non-zero code. 530 The database file is assured to be kept synchronized and not modified while the copying or 531 executing operation is in progress. So, this function is useful to create a backup file of 532 the database file. */ 533 bool tchdbcopy(TCHDB *hdb, const char *path); 534 535 536 /* Begin the transaction of a hash database object. 537 `hdb' specifies the hash database object connected as a writer. 538 If successful, the return value is true, else, it is false. 539 The database is locked by the thread while the transaction so that only one transaction can be 540 activated with a database object at the same time. Thus, the serializable isolation level is 541 assumed if every database operation is performed in the transaction. All updated regions are 542 kept track of by write ahead logging while the transaction. If the database is closed during 543 transaction, the transaction is aborted implicitly. */ 544 bool tchdbtranbegin(TCHDB *hdb); 545 546 547 /* Commit the transaction of a hash database object. 548 `hdb' specifies the hash database object connected as a writer. 549 If successful, the return value is true, else, it is false. 550 Update in the transaction is fixed when it is committed successfully. */ 551 bool tchdbtrancommit(TCHDB *hdb); 552 553 554 /* Abort the transaction of a hash database object. 555 `hdb' specifies the hash database object connected as a writer. 556 If successful, the return value is true, else, it is false. 557 Update in the transaction is discarded when it is aborted. The state of the database is 558 rollbacked to before transaction. */ 559 bool tchdbtranabort(TCHDB *hdb); 560 561 562 /* Get the file path of a hash database object. 563 `hdb' specifies the hash database object. 564 The return value is the path of the database file or `NULL' if the object does not connect to 565 any database file. */ 566 const char *tchdbpath(TCHDB *hdb); 567 568 569 /* Get the number of records of a hash database object. 570 `hdb' specifies the hash database object. 571 The return value is the number of records or 0 if the object does not connect to any database 572 file. */ 573 uint64_t tchdbrnum(TCHDB *hdb); 574 575 576 /* Get the size of the database file of a hash database object. 577 `hdb' specifies the hash database object. 578 The return value is the size of the database file or 0 if the object does not connect to any 579 database file. */ 580 uint64_t tchdbfsiz(TCHDB *hdb); 581 582 583 584 /************************************************************************************************* 585 * features for experts 586 *************************************************************************************************/ 587 588 589 /* Set the error code of a hash database object. 590 `hdb' specifies the hash database object. 591 `ecode' specifies the error code. 592 `file' specifies the file name of the code. 593 `line' specifies the line number of the code. 594 `func' specifies the function name of the code. */ 595 void tchdbsetecode(TCHDB *hdb, int ecode, const char *filename, int line, const char *func); 596 597 598 /* Set the type of a hash database object. 599 `hdb' specifies the hash database object. 600 `type' specifies the database type. */ 601 void tchdbsettype(TCHDB *hdb, uint8_t type); 602 603 604 /* Set the file descriptor for debugging output. 605 `hdb' specifies the hash database object. 606 `fd' specifies the file descriptor for debugging output. */ 607 void tchdbsetdbgfd(TCHDB *hdb, int fd); 608 609 610 /* Get the file descriptor for debugging output. 611 `hdb' specifies the hash database object. 612 The return value is the file descriptor for debugging output. */ 613 int tchdbdbgfd(TCHDB *hdb); 614 615 616 /* Check whether mutual exclusion control is set to a hash database object. 617 `hdb' specifies the hash database object. 618 If mutual exclusion control is set, it is true, else it is false. */ 619 bool tchdbhasmutex(TCHDB *hdb); 620 621 622 /* Synchronize updating contents on memory of a hash database object. 623 `hdb' specifies the hash database object connected as a writer. 624 `phys' specifies whether to synchronize physically. 625 If successful, the return value is true, else, it is false. */ 626 bool tchdbmemsync(TCHDB *hdb, bool phys); 627 628 629 /* Get the number of elements of the bucket array of a hash database object. 630 `hdb' specifies the hash database object. 631 The return value is the number of elements of the bucket array or 0 if the object does not 632 connect to any database file. */ 633 uint64_t tchdbbnum(TCHDB *hdb); 634 635 636 /* Get the record alignment of a hash database object. 637 `hdb' specifies the hash database object. 638 The return value is the record alignment or 0 if the object does not connect to any database 639 file. */ 640 uint32_t tchdbalign(TCHDB *hdb); 641 642 643 /* Get the maximum number of the free block pool of a a hash database object. 644 `hdb' specifies the hash database object. 645 The return value is the maximum number of the free block pool or 0 if the object does not 646 connect to any database file. */ 647 uint32_t tchdbfbpmax(TCHDB *hdb); 648 649 650 /* Get the size of the extra mapped memory of a hash database object. 651 `hdb' specifies the hash database object. 652 The return value is the size of the extra mapped memory or 0 if the object does not connect to 653 any database file. */ 654 uint64_t tchdbxmsiz(TCHDB *hdb); 655 656 657 /* Get the inode number of the database file of a hash database object. 658 `hdb' specifies the hash database object. 659 The return value is the inode number of the database file or 0 if the object does not connect 660 to any database file. */ 661 uint64_t tchdbinode(TCHDB *hdb); 662 663 664 /* Get the modification time of the database file of a hash database object. 665 `hdb' specifies the hash database object. 666 The return value is the inode number of the database file or 0 if the object does not connect 667 to any database file. */ 668 time_t tchdbmtime(TCHDB *hdb); 669 670 671 /* Get the connection mode of a hash database object. 672 `hdb' specifies the hash database object. 673 The return value is the connection mode. */ 674 int tchdbomode(TCHDB *hdb); 675 676 677 /* Get the database type of a hash database object. 678 `hdb' specifies the hash database object. 679 The return value is the database type. */ 680 uint8_t tchdbtype(TCHDB *hdb); 681 682 683 /* Get the additional flags of a hash database object. 684 `hdb' specifies the hash database object. 685 The return value is the additional flags. */ 686 uint8_t tchdbflags(TCHDB *hdb); 687 688 689 /* Get the options of a hash database object. 690 `hdb' specifies the hash database object. 691 The return value is the options. */ 692 uint8_t tchdbopts(TCHDB *hdb); 693 694 695 /* Get the pointer to the opaque field of a hash database object. 696 `hdb' specifies the hash database object. 697 The return value is the pointer to the opaque field whose size is 128 bytes. */ 698 char *tchdbopaque(TCHDB *hdb); 699 700 701 /* Get the number of used elements of the bucket array of a hash database object. 702 `hdb' specifies the hash database object. 703 The return value is the number of used elements of the bucket array or 0 if the object does 704 not connect to any database file. */ 705 uint64_t tchdbbnumused(TCHDB *hdb); 706 707 708 /* Set the custom codec functions of a hash database object. 709 `hdb' specifies the hash database object. 710 `enc' specifies the pointer to the custom encoding function. It receives four parameters. 711 The first parameter is the pointer to the region. The second parameter is the size of the 712 region. The third parameter is the pointer to the variable into which the size of the region 713 of the return value is assigned. The fourth parameter is the pointer to the optional opaque 714 object. It returns the pointer to the result object allocated with `malloc' call if 715 successful, else, it returns `NULL'. 716 `encop' specifies an arbitrary pointer to be given as a parameter of the encoding function. 717 If it is not needed, `NULL' can be specified. 718 `dec' specifies the pointer to the custom decoding function. 719 `decop' specifies an arbitrary pointer to be given as a parameter of the decoding function. 720 If it is not needed, `NULL' can be specified. 721 If successful, the return value is true, else, it is false. 722 Note that the custom codec functions should be set before the database is opened and should be 723 set every time the database is being opened. */ 724 bool tchdbsetcodecfunc(TCHDB *hdb, TCCODEC enc, void *encop, TCCODEC dec, void *decop); 725 726 727 /* Get the custom codec functions of a hash database object. 728 `hdb' specifies the hash database object. 729 `ep' specifies the pointer to a variable into which the pointer to the custom encoding 730 function is assigned 731 `eop' specifies the pointer to a variable into which the arbitrary pointer to be given to the 732 encoding function is assigned. 733 `dp' specifies the pointer to a variable into which the pointer to the custom decoding 734 function is assigned 735 `dop' specifies the pointer to a variable into which the arbitrary pointer to be given to the 736 decoding function is assigned. */ 737 void tchdbcodecfunc(TCHDB *hdb, TCCODEC *ep, void **eop, TCCODEC *dp, void **dop); 738 739 740 /* Get the unit step number of auto defragmentation of a hash database object. 741 `hdb' specifies the hash database object. 742 The return value is the unit step number of auto defragmentation. */ 743 uint32_t tchdbdfunit(TCHDB *hdb); 744 745 746 /* Perform dynamic defragmentation of a hash database object. 747 `hdb' specifies the hash database object connected as a writer. 748 `step' specifie the number of steps. If it is not more than 0, the whole file is defragmented 749 gradually without keeping a continuous lock. 750 If successful, the return value is true, else, it is false. */ 751 bool tchdbdefrag(TCHDB *hdb, int64_t step); 752 753 754 /* Clear the cache of a hash tree database object. 755 `hdb' specifies the hash tree database object. 756 If successful, the return value is true, else, it is false. */ 757 bool tchdbcacheclear(TCHDB *hdb); 758 759 760 /* Store a record into a hash database object with a duplication handler. 761 `hdb' specifies the hash database object connected as a writer. 762 `kbuf' specifies the pointer to the region of the key. 763 `ksiz' specifies the size of the region of the key. 764 `vbuf' specifies the pointer to the region of the value. `NULL' means that record addition is 765 ommited if there is no corresponding record. 766 `vsiz' specifies the size of the region of the value. 767 `proc' specifies the pointer to the callback function to process duplication. It receives 768 four parameters. The first parameter is the pointer to the region of the value. The second 769 parameter is the size of the region of the value. The third parameter is the pointer to the 770 variable into which the size of the region of the return value is assigned. The fourth 771 parameter is the pointer to the optional opaque object. It returns the pointer to the result 772 object allocated with `malloc'. It is released by the caller. If it is `NULL', the record is 773 not modified. If it is `(void *)-1', the record is removed. 774 `op' specifies an arbitrary pointer to be given as a parameter of the callback function. If 775 it is not needed, `NULL' can be specified. 776 If successful, the return value is true, else, it is false. 777 Note that the callback function can not perform any database operation because the function 778 is called in the critical section guarded by the same locks of database operations. */ 779 bool tchdbputproc(TCHDB *hdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz, 780 TCPDPROC proc, void *op); 781 782 783 /* Retrieve the next record of a record in a hash database object. 784 `hdb' specifies the hash database object. 785 `kbuf' specifies the pointer to the region of the key. If it is `NULL', the first record is 786 retrieved. 787 `ksiz' specifies the size of the region of the key. 788 `sp' specifies the pointer to the variable into which the size of the region of the return 789 value is assigned. 790 If successful, the return value is the pointer to the region of the key of the next record. 791 `NULL' is returned if no record corresponds. 792 Because an additional zero code is appended at the end of the region of the return value, 793 the return value can be treated as a character string. Because the region of the return 794 value is allocated with the `malloc' call, it should be released with the `free' call when 795 it is no longer in use. */ 796 void *tchdbgetnext(TCHDB *hdb, const void *kbuf, int ksiz, int *sp); 797 798 799 /* Retrieve the next string record in a hash database object. 800 `hdb' specifies the hash database object. 801 `kstr' specifies the string of the key. If it is `NULL', the first record is retrieved. 802 If successful, the return value is the string of the key of the next record. `NULL' is 803 returned if no record corresponds. 804 Because the region of the return value is allocated with the `malloc' call, it should be 805 released with the `free' call when it is no longer in use. */ 806 char *tchdbgetnext2(TCHDB *hdb, const char *kstr); 807 808 809 /* Retrieve the key and the value of the next record of a record in a hash database object. 810 `hdb' specifies the hash database object. 811 `kbuf' specifies the pointer to the region of the key. 812 `ksiz' specifies the size of the region of the key. 813 `sp' specifies the pointer to the variable into which the size of the region of the return 814 value is assigned. 815 `vbp' specifies the pointer to the variable into which the pointer to the value is assigned. 816 `vsp' specifies the pointer to the variable into which the size of the value is assigned. 817 If successful, the return value is the pointer to the region of the key of the next 818 record. 819 Because the region of the return value is allocated with the `malloc' call, it should be 820 released with the `free' call when it is no longer in use. The retion pointed to by `vbp' 821 should not be released. */ 822 char *tchdbgetnext3(TCHDB *hdb, const char *kbuf, int ksiz, int *sp, const char **vbp, int *vsp); 823 824 825 /* Move the iterator to the record corresponding a key of a hash database object. 826 `hdb' specifies the hash database object. 827 `kbuf' specifies the pointer to the region of the key. 828 `ksiz' specifies the size of the region of the key. 829 If successful, the return value is true, else, it is false. False is returned if there is 830 no record corresponding the condition. */ 831 bool tchdbiterinit2(TCHDB *hdb, const void *kbuf, int ksiz); 832 833 834 /* Move the iterator to the record corresponding a key string of a hash database object. 835 `hdb' specifies the hash database object. 836 `kstr' specifies the string of the key. 837 If successful, the return value is true, else, it is false. False is returned if there is 838 no record corresponding the condition. */ 839 bool tchdbiterinit3(TCHDB *hdb, const char *kstr); 840 841 842 /* Process each record atomically of a hash database object. 843 `hdb' specifies the hash database object. 844 `iter' specifies the pointer to the iterator function called for each record. It receives 845 five parameters. The first parameter is the pointer to the region of the key. The second 846 parameter is the size of the region of the key. The third parameter is the pointer to the 847 region of the value. The fourth parameter is the size of the region of the value. The fifth 848 parameter is the pointer to the optional opaque object. It returns true to continue iteration 849 or false to stop iteration. 850 `op' specifies an arbitrary pointer to be given as a parameter of the iterator function. If 851 it is not needed, `NULL' can be specified. 852 If successful, the return value is true, else, it is false. 853 Note that the callback function can not perform any database operation because the function 854 is called in the critical section guarded by the same locks of database operations. */ 855 bool tchdbforeach(TCHDB *hdb, TCITER iter, void *op); 856 857 858 /* Void the transaction of a hash database object. 859 `hdb' specifies the hash database object connected as a writer. 860 If successful, the return value is true, else, it is false. 861 This function should be called only when no update in the transaction. */ 862 bool tchdbtranvoid(TCHDB *hdb); 863 864 865 866 __TCHDB_CLINKAGEEND 867 #endif /* duplication check */ 868 869 870 /* END OF FILE */ 871