tctdb.h

Tokyo Cabinet的Tokyo Cabinet 是一个DBM的实现。这里的数据库由一系列key-value对的记录构成。key和value都可以是任意长度的字节序列,既可以是二进制也可以是字符

/*************************************************************************************************
 * The table database API of Tokyo Cabinet
 *                                                      Copyright (C) 2006-2009 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 _TCTDB_H                         /* duplication check */
#define _TCTDB_H

#if defined(__cplusplus)
#define __TCTDB_CLINKAGEBEGIN extern "C" {
#define __TCTDB_CLINKAGEEND }
#else
#define __TCTDB_CLINKAGEBEGIN
#define __TCTDB_CLINKAGEEND
#endif
__TCTDB_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>
#include <tcbdb.h>



/*************************************************************************************************
 * API
 *************************************************************************************************/


typedef struct {                         /* type of structure for a column index */
  char *name;                            /* column name */
  int type;                              /* data type */
  void *db;                              /* internal database object */
} TDBIDX;

typedef struct {                         /* type of structure for a table database */
  void *mmtx;                            /* mutex for method */
  TCHDB *hdb;                            /* internal database object */
  bool open;                             /* whether the internal database is opened */
  bool wmode;                            /* whether to be writable */
  uint8_t opts;                          /* options */
  int32_t lcnum;                         /* max number of cached leaves */
  int32_t ncnum;                         /* max number of cached nodes */
  TDBIDX *idxs;                          /* column indices */
  int inum;                              /* number of column indices */
  bool tran;                             /* whether in the transaction */
} TCTDB;

enum {                                   /* enumeration for additional flags */
  TDBFOPEN = HDBFOPEN,                   /* whether opened */
  TDBFFATAL = HDBFFATAL                  /* whetehr with fatal error */
};

enum {                                   /* enumeration for tuning options */
  TDBTLARGE = 1 << 0,                    /* use 64-bit bucket array */
  TDBTDEFLATE = 1 << 1,                  /* compress each page with Deflate */
  TDBTBZIP = 1 << 2,                     /* compress each record with BZIP2 */
  TDBTTCBS = 1 << 3,                     /* compress each page with TCBS */
  TDBTEXCODEC = 1 << 4                   /* compress each record with outer functions */
};

enum {                                   /* enumeration for open modes */
  TDBOREADER = 1 << 0,                   /* open as a reader */
  TDBOWRITER = 1 << 1,                   /* open as a writer */
  TDBOCREAT = 1 << 2,                    /* writer creating */
  TDBOTRUNC = 1 << 3,                    /* writer truncating */
  TDBONOLCK = 1 << 4,                    /* open without locking */
  TDBOLCKNB = 1 << 5,                    /* lock without blocking */
  TDBOTSYNC = 1 << 6                     /* synchronize every transaction */
};

enum {                                   /* enumeration for index types */
  TDBITLEXICAL,                          /* lexical string */
  TDBITDECIMAL,                          /* decimal string */
  TDBITOPT = 9998,                       /* optimize */
  TDBITVOID = 9999,                      /* void */
  TDBITKEEP = 1 << 24                    /* keep existing index */
};

typedef struct {                         /* type of structure for a condition */
  char *name;                            /* column name */
  int nsiz;                              /* size of the column name */
  int op;                                /* operation type */
  bool sign;                             /* positive sign */
  bool noidx;                            /* no index flag */
  char *expr;                            /* operand expression */
  int esiz;                              /* size of the operand expression */
  bool alive;                            /* alive flag */
} TDBCOND;

typedef struct {                         /* type of structure for a query */
  TCTDB *tdb;                            /* database object */
  TDBCOND *conds;                        /* condition objects */
  int cnum;                              /* number of conditions */
  char *oname;                           /* column name for ordering */
  int otype;                             /* type of order */
  int max;                               /* max number of retrieval */
  int skip;                              /* skipping number of retrieval */
  TCXSTR *hint;                          /* hint string */
  int count;                             /* count of corresponding records */
} TDBQRY;

enum {                                   /* enumeration for query conditions */
  TDBQCSTREQ,                            /* string is equal to */
  TDBQCSTRINC,                           /* string is included in */
  TDBQCSTRBW,                            /* string begins with */
  TDBQCSTREW,                            /* string ends with */
  TDBQCSTRAND,                           /* string includes all tokens in */
  TDBQCSTROR,                            /* string includes at least one token in */
  TDBQCSTROREQ,                          /* string is equal to at least one token in */
  TDBQCSTRRX,                            /* string matches regular expressions of */
  TDBQCNUMEQ,                            /* number is equal to */
  TDBQCNUMGT,                            /* number is greater than */
  TDBQCNUMGE,                            /* number is greater than or equal to */
  TDBQCNUMLT,                            /* number is less than */
  TDBQCNUMLE,                            /* number is less than or equal to */
  TDBQCNUMBT,                            /* number is between two tokens of */
  TDBQCNUMOREQ,                          /* number is equal to at least one token in */
  TDBQCNEGATE = 1 << 24,                 /* negation flag */
  TDBQCNOIDX = 1 << 25                   /* no index flag */
};

enum {                                   /* enumeration for order types */
  TDBQOSTRASC,                           /* string ascending */
  TDBQOSTRDESC,                          /* string descending */
  TDBQONUMASC,                           /* number ascending */
  TDBQONUMDESC                           /* number descending */
};

enum {                                   /* enumeration for post treatments */
  TDBQPPUT = 1 << 0,                     /* modify the record */
  TDBQPOUT = 1 << 1,                     /* remove the record */
  TDBQPSTOP = 1 << 24                    /* stop the iteration */
};

/* type of the pointer to a iterator function for each table record.
   `pkbuf' specifies the pointer to the region of the primary key.
   `pksiz' specifies the size of the region of the primary key.
   `cols' specifies a map object containing columns.
   `op' specifies the pointer to the optional opaque object.
   The return value is flags of the post treatment by bitwise-or: `TDBQPPUT' to modify the
   record, `TDBQPOUT' to remove the record, `TDBQPSTOP' to stop the iteration. */
typedef int (*TDBQRYPROC)(const void *pkbuf, int pksiz, TCMAP *cols, void *op);


/* 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 *tctdberrmsg(int ecode);


/* Create a table database object.
   The return value is the new table database object. */
TCTDB *tctdbnew(void);


/* Delete a table database object.
   `tdb' specifies the table 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 tctdbdel(TCTDB *tdb);


/* Get the last happened error code of a table database object.
   `tdb' specifies the table database object.
   The return value is the last happened error code.
   The following error code is 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 tctdbecode(TCTDB *tdb);


/* Set mutual exclusion control of a table database object for threading.
   `tdb' specifies the table 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 tctdbsetmutex(TCTDB *tdb);


/* Set the tuning parameters of a table database object.
   `tdb' specifies the table database object which is not opened.
   `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 131071.  Suggested size of the bucket array
   is about from 0.5 to 4 times of the number of all records 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 4 standing for 2^4=16.
   `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: `TDBTLARGE' specifies that the size of the database
   can be larger than 2GB by using 64-bit bucket array, `TDBTDEFLATE' specifies that each record
   is compressed with Deflate encoding, `TDBTBZIP' specifies that each record is compressed with
   BZIP2 encoding, `TDBTTCBS' specifies that each record 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 tctdbtune(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);


/* Set the caching parameters of a table database object.
   `tdb' specifies the table database object which is not opened.
   `rcnum' specifies the maximum number of records to be cached.  If it is not more than 0, the