/************************************************************************************************* * The B+ tree database API of Tokyo Cabinet *                                                      Copyright (C) 2006-2008 Mikio Hirabayashi * This file is part of Tokyo Cabinet. * Tokyo Cabinet is free software; you can redistribute it and/or modify it under the terms of * the GNU Lesser General Public License as published by the Free Software Foundation; either * version 2.1 of the License or any later version.  Tokyo Cabinet is distributed in the hope * that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public * License for more details. * You should have received a copy of the GNU Lesser General Public License along with Tokyo * Cabinet; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, * Boston, MA 02111-1307 USA. *************************************************************************************************/#ifndef _TCBDB_H                         /* duplication check */#define _TCBDB_H#if defined(__cplusplus)#define __TCBDB_CLINKAGEBEGIN extern "C" {#define __TCBDB_CLINKAGEEND }#else#define __TCBDB_CLINKAGEBEGIN#define __TCBDB_CLINKAGEEND#endif__TCBDB_CLINKAGEBEGIN#include <stdlib.h>#include <stdbool.h>#include <stdint.h>#include <time.h>#include <limits.h>#include <math.h>#include <tcutil.h>#include <tchdb.h>/************************************************************************************************* * API *************************************************************************************************//* type of the pointer to a comparison function.   `aptr' specifies the pointer to the region of one key.   `asiz' specifies the size of the region of one key.   `bptr' specifies the pointer to the region of the other key.   `bsiz' specifies the size of the region of the other key.   `op' specifies the pointer to the optional opaque object.   The return value is positive if the former is big, negative if the latter is big, 0 if both   are equivalent. */typedef int (*BDBCMP)(const char *aptr, int asiz, const char *bptr, int bsiz, void *op);/* type of the pointer to a encoding or decoding function.   `ptr' specifies the pointer to the region.   `size' specifies the size of the region.   `sp' specifies the pointer to the variable into which the size of the region of the return   value is assigned.   `op' specifies the pointer to the optional opaque object.   If successful, the return value is the pointer to the result object allocated with `malloc'   call, else, it is `NULL'. */typedef void *(*BDBCODEC)(const void *ptr, int size, int *sp, void *op);typedef struct {                         /* type of structure for a B+ tree database */  void *mmtx;                            /* mutex for method */  void *cmtx;                            /* mutex for cache */  void *tmtx;                            /* mutex for transaction */  TCHDB *hdb;                            /* internal database object */  char *opaque;                          /* opaque buffer */  bool open;                             /* whether the internal database is opened */  bool wmode;                            /* whether to be writable */  uint32_t lmemb;                        /* number of members in each leaf */  uint32_t nmemb;                        /* number of members in each node */  uint8_t opts;                          /* options */  uint64_t root;                         /* ID number of the root page */  uint64_t first;                        /* ID number of the first leaf */  uint64_t last;                         /* ID number of the last leaf */  uint64_t lnum;                         /* number of leaves */  uint64_t nnum;                         /* number of nodes */  uint64_t rnum;                         /* number of records */  TCMAP *leafc;                          /* cache for leaves */  TCMAP *nodec;                          /* cache for nodes */  BDBCMP cmp;                            /* pointer to the comparison function */  void *cmpop;                           /* opaque object for the comparison function */  uint32_t lcnum;                        /* max number of cached leaves */  uint32_t ncnum;                        /* max number of cached nodes */  uint32_t lsmax;                        /* max size of each leaf */  uint32_t lschk;                        /* counter for leaf size checking */  uint64_t capnum;                       /* capacity number of records */  uint64_t *hist;                        /* history array of visited nodes */  int hnum;                              /* number of element of the history array */  uint64_t hleaf;                        /* ID number of the leaf referred by the history */  uint64_t lleaf;                        /* ID number of the last visited leaf */  bool tran;                             /* whether in the transaction */  char *rbopaque;                        /* opaque for rollback */  int64_t cnt_saveleaf;                  /* tesing counter for leaf save times */  int64_t cnt_loadleaf;                  /* tesing counter for leaf load times */  int64_t cnt_killleaf;                  /* tesing counter for leaf kill times */  int64_t cnt_adjleafc;                  /* tesing counter for node cache adjust times */  int64_t cnt_savenode;                  /* tesing counter for node save times */  int64_t cnt_loadnode;                  /* tesing counter for node load times */  int64_t cnt_adjnodec;                  /* tesing counter for node cache adjust times */} TCBDB;enum {                                   /* enumeration for additional flags */  BDBFOPEN = HDBFOPEN,                   /* whether opened */  BDBFFATAL = HDBFFATAL                  /* whetehr with fatal error */};enum {                                   /* enumeration for tuning options */  BDBTLARGE = 1 << 0,                    /* use 64-bit bucket array */  BDBTDEFLATE = 1 << 1,                  /* compress each page with Deflate */  BDBTBZIP = 1 << 2,                     /* compress each record with BZIP2 */  BDBTTCBS = 1 << 3,                     /* compress each page with TCBS */  BDBTEXCODEC = 1 << 4                   /* compress each record with outer functions */};enum {                                   /* enumeration for open modes */  BDBOREADER = 1 << 0,                   /* open as a reader */  BDBOWRITER = 1 << 1,                   /* open as a writer */  BDBOCREAT = 1 << 2,                    /* writer creating */  BDBOTRUNC = 1 << 3,                    /* writer truncating */  BDBONOLCK = 1 << 4,                    /* open without locking */  BDBOLCKNB = 1 << 5                     /* lock without blocking */};typedef struct {                         /* type of structure for a B+ tree cursor */  TCBDB *bdb;                            /* database object */  uint64_t id;                           /* ID number of the leaf */  int32_t kidx;                          /* number of the key */  int32_t vidx;                          /* number of the value */} BDBCUR;enum {                                   /* enumeration for cursor put mode */  BDBCPCURRENT,                          /* current */  BDBCPBEFORE,                           /* before */  BDBCPAFTER                             /* after */};/* Get the message string corresponding to an error code.   `ecode' specifies the error code.   The return value is the message string of the error code. */const char *tcbdberrmsg(int ecode);/* Create a B+ tree database object.   The return value is the new B+ tree database object. */TCBDB *tcbdbnew(void);/* Delete a B+ tree database object.   `bdb' specifies the B+ tree database object.   If the database is not closed, it is closed implicitly.  Note that the deleted object and its   derivatives can not be used anymore. */void tcbdbdel(TCBDB *bdb);/* Get the last happened error code of a B+ tree database object.   `bdb' specifies the B+ tree database object.   The return value is the last happened error code.   The following error codes are defined: `TCESUCCESS' for success, `TCETHREAD' for threading   error, `TCEINVALID' for invalid operation, `TCENOFILE' for file not found, `TCENOPERM' for no   permission, `TCEMETA' for invalid meta data, `TCERHEAD' for invalid record header, `TCEOPEN'   for open error, `TCECLOSE' for close error, `TCETRUNC' for trunc error, `TCESYNC' for sync   error, `TCESTAT' for stat error, `TCESEEK' for seek error, `TCEREAD' for read error,   `TCEWRITE' for write error, `TCEMMAP' for mmap error, `TCELOCK' for lock error, `TCEUNLINK'   for unlink error, `TCERENAME' for rename error, `TCEMKDIR' for mkdir error, `TCERMDIR' for   rmdir error, `TCEKEEP' for existing record, `TCENOREC' for no record found, and `TCEMISC' for   miscellaneous error. */int tcbdbecode(TCBDB *bdb);/* Set mutual exclusion control of a B+ tree database object for threading.   `bdb' specifies the B+ tree database object which is not opened.   If successful, the return value is true, else, it is false.   Note that the mutual exclusion control is needed if the object is shared by plural threads and   this function should should be called before the database is opened. */bool tcbdbsetmutex(TCBDB *bdb);/* Set the custom comparison function of a B+ tree database object.   `bdb' specifies the B+ tree database object which is not opened.   `cmp' specifies the pointer to the custom comparison function.   `cmpop' specifies an arbitrary pointer to be given as a parameter of the comparison function.   If it is not needed, `NULL' can be specified.   If successful, the return value is true, else, it is false.   The default comparison function compares keys of two records by lexical order.  The functions   `tcbdbcmplexical' (dafault), `tcbdbcmpdecimal', `tcbdbcmpint32', and `tcbdbcmpint64' are   built-in.  Note that the comparison function should be set before the database is opened.   Moreover, user-defined comparison functions should be set every time the database is being   opened. */bool tcbdbsetcmpfunc(TCBDB *bdb, BDBCMP cmp, void *cmpop);/* Set the tuning parameters of a B+ tree database object.   `bdb' specifies the B+ tree database object which is not opened.   `lmemb' specifies the number of members in each leaf page.  If it is not more than 0, the   default value is specified.  The default value is 128.   `nmemb' specifies the number of members in each non-leaf page.  If it is not more than 0, the   default value is specified.  The default value is 256.   `bnum' specifies the number of elements of the bucket array.  If it is not more than 0, the   default value is specified.  The default value is 32749.  Suggested size of the bucket array   is about from 1 to 4 times of the number of all pages to be stored.   `apow' specifies the size of record alignment by power of 2.  If it is negative, the default   value is specified.  The default value is 8 standing for 2^8=256.   `fpow' specifies the maximum number of elements of the free block pool by power of 2.  If it   is negative, the default value is specified.  The default value is 10 standing for 2^10=1024.   `opts' specifies options by bitwise or: `BDBTLARGE' specifies that the size of the database   can be larger than 2GB by using 64-bit bucket array, `BDBTDEFLATE' specifies that each page   is compressed with Deflate encoding, `BDBTBZIP' specifies that each page is compressed with   BZIP2 encoding, `BDBTTCBS' specifies that each page is compressed with TCBS encoding.   If successful, the return value is true, else, it is false.   Note that the tuning parameters should be set before the database is opened. */bool tcbdbtune(TCBDB *bdb, int32_t lmemb, int32_t nmemb,               int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);/* Set the caching parameters of a B+ tree database object.   `bdb' specifies the B+ tree database object which is not opened.   `lcnum' specifies the maximum number of leaf nodes to be cached.  If it is not more than 0,   the default value is specified.  The default value is 1024.   `ncnum' specifies the maximum number of non-leaf nodes to be cached.  If it is not more than 0,   the default value is specified.  The default value is 512.   If successful, the return value is true, else, it is false.   Note that the caching parameters should be set before the database is opened. */bool tcbdbsetcache(TCBDB *bdb, int32_t lcnum, int32_t ncnum);/* Set the size of the extra mapped memory of a B+ tree database object.   `bdb' specifies the B+ tree database object which is not opened.   `xmsiz' specifies the size of the extra mapped memory.  If it is not more than 0, the extra   mapped memory is disabled.  It is disabled by default.   If successful, the return value is true, else, it is false.   Note that the mapping parameters should be set before the database is opened. */bool tcbdbsetxmsiz(TCBDB *bdb, int64_t xmsiz);/* Open a database file and connect a B+ tree database object.   `bdb' specifies the B+ tree database object which is not opened.   `path' specifies the path of the database file.   `omode' specifies the connection mode: `BDBOWRITER' as a writer, `BDBOREADER' as a reader.   If the mode is `BDBOWRITER', the following may be added by bitwise or: `BDBOCREAT', which   means it creates a new database if not exist, `BDBOTRUNC', which means it creates a new database   regardless if one exists.  Both of `BDBOREADER' and `BDBOWRITER' can be added to by   bitwise or: `BDBONOLCK', which means it opens the database file without file locking, or   `BDBOLCKNB', which means locking is performed without blocking.   If successful, the return value is true, else, it is false. */bool tcbdbopen(TCBDB *bdb, const char *path, int omode);/* Close a B+ tree database object.   `bdb' specifies the B+ tree database object.   If successful, the return value is true, else, it is false.   Update of a database is assured to be written when the database is closed.  If a writer opens   a database but does not close it appropriately, the database will be broken. */bool tcbdbclose(TCBDB *bdb);/* Store a record into a B+ tree database object.   `bdb' specifies the B+ tree database object connected as a writer.   `kbuf' specifies the pointer to the region of the key.   `ksiz' specifies the size of the region of the key.   `vbuf' specifies the pointer to the region of the value.   `vsiz' specifies the size of the region of the value.   If successful, the return value is true, else, it is false.   If a record with the same key exists in the database, it is overwritten. */bool tcbdbput(TCBDB *bdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);/* Store a string record into a B+ tree database object.   `bdb' specifies the B+ tree database object connected as a writer.