tcfdb.h

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

/*************************************************************************************************
 * The fixed-length 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 _TCFDB_H                         /* duplication check */
#define _TCFDB_H

#if defined(__cplusplus)
#define __TCFDB_CLINKAGEBEGIN extern "C" {
#define __TCFDB_CLINKAGEEND }
#else
#define __TCFDB_CLINKAGEBEGIN
#define __TCFDB_CLINKAGEEND
#endif
__TCFDB_CLINKAGEBEGIN


#include <stdlib.h>
#include <stdbool.h>
#include <stdint.h>
#include <time.h>
#include <limits.h>
#include <math.h>
#include <tcutil.h>



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


typedef struct {                         /* type of structure for a fixed-length database */
  void *mmtx;                            /* mutex for method */
  void *amtx;                            /* mutex for attribute */
  void *rmtxs;                           /* mutexes for records */
  void *tmtx;                            /* mutex for transaction */
  void *wmtx;                            /* mutex for write ahead logging */
  void *eckey;                           /* key for thread specific error code */
  uint8_t type;                          /* database type */
  uint8_t flags;                         /* additional flags */
  uint32_t width;                        /* width of the value of each record */
  uint64_t limsiz;                       /* limit size of the file */
  int wsiz;                              /* size of the width region */
  int rsiz;                              /* size of each record */
  uint64_t limid;                        /* limit ID number */
  char *path;                            /* path of the database file */
  int fd;                                /* file descriptor of the database file */
  uint32_t omode;                        /* open mode */
  uint64_t rnum;                         /* number of the records */
  uint64_t fsiz;                         /* size of the database file */
  uint64_t min;                          /* minimum ID number */
  uint64_t max;                          /* maximum ID number */
  uint64_t iter;                         /* ID number of the iterator */
  char *map;                             /* pointer to the mapped memory */
  unsigned char *array;                  /* pointer to the array region */
  int ecode;                             /* last happened error code */
  bool fatal;                            /* whether a fatal error occured */
  uint64_t inode;                        /* inode number */
  time_t mtime;                          /* modification time */
  bool tran;                             /* whether in the transaction */
  int walfd;                             /* file descriptor of write ahead logging */
  uint64_t walend;                       /* end offset of write ahead logging */
  int dbgfd;                             /* file descriptor for debugging */
  int64_t cnt_writerec;                  /* tesing counter for record write times */
  int64_t cnt_readrec;                   /* tesing counter for record read times */
  int64_t cnt_truncfile;                 /* tesing counter for file truncate times */
} TCFDB;

enum {                                   /* enumeration for additional flags */
  FDBFOPEN = 1 << 0,                     /* whether opened */
  FDBFFATAL = 1 << 1                     /* whetehr with fatal error */
};

enum {                                   /* enumeration for open modes */
  FDBOREADER = 1 << 0,                   /* open as a reader */
  FDBOWRITER = 1 << 1,                   /* open as a writer */
  FDBOCREAT = 1 << 2,                    /* writer creating */
  FDBOTRUNC = 1 << 3,                    /* writer truncating */
  FDBONOLCK = 1 << 4,                    /* open without locking */
  FDBOLCKNB = 1 << 5,                    /* lock without blocking */
  FDBOTSYNC = 1 << 6                     /* synchronize every transaction */
};

enum {                                   /* enumeration for ID constants */
  FDBIDMIN = -1,                         /* minimum number */
  FDBIDPREV = -2,                        /* less by one than the minimum */
  FDBIDMAX = -3,                         /* maximum number */
  FDBIDNEXT = -4                         /* greater by one than the miximum */
};


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


/* Create a fixed-length database object.
   The return value is the new fixed-length database object. */
TCFDB *tcfdbnew(void);


/* Delete a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbdel(TCFDB *fdb);


/* Get the last happened error code of a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbecode(TCFDB *fdb);


/* Set mutual exclusion control of a fixed-length database object for threading.
   `fdb' specifies the fixed-length 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 tcfdbsetmutex(TCFDB *fdb);


/* Set the tuning parameters of a fixed-length database object.
   `fdb' specifies the fixed-length database object which is not opened.
   `width' specifies the width of the value of each record.  If it is not more than 0, the
   default value is specified.  The default value is 255.
   `limsiz' specifies the limit size of the database file.  If it is not more than 0, the default
   value is specified.  The default value is 268435456.
   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 tcfdbtune(TCFDB *fdb, int32_t width, int64_t limsiz);


/* Open a database file and connect a fixed-length database object.
   `fdb' specifies the fixed-length database object which is not opened.
   `path' specifies the path of the database file.
   `omode' specifies the connection mode: `FDBOWRITER' as a writer, `FDBOREADER' as a reader.
   If the mode is `FDBOWRITER', the following may be added by bitwise-or: `FDBOCREAT', which
   means it creates a new database if not exist, `FDBOTRUNC', which means it creates a new
   database regardless if one exists, `FDBOTSYNC', which means every transaction synchronizes
   updated contents with the device.  Both of `FDBOREADER' and `FDBOWRITER' can be added to by
   bitwise-or: `FDBONOLCK', which means it opens the database file without file locking, or
   `FDBOLCKNB', which means locking is performed without blocking.
   If successful, the return value is true, else, it is false. */
bool tcfdbopen(TCFDB *fdb, const char *path, int omode);


/* Close a fixed-length database object.
   `fdb' specifies the fixed-length 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 tcfdbclose(TCFDB *fdb);


/* Store a record into a fixed-length database object.
   `fdb' specifies the fixed-length database object connected as a writer.
   `id' specifies the ID number.  It should be more than 0.  If it is `FDBIDMIN', the minimum ID
   number of existing records is specified.  If it is `FDBIDPREV', the number less by one than
   the minimum ID number of existing records is specified.  If it is `FDBIDMAX', the maximum ID
   number of existing records is specified.  If it is `FDBIDNEXT', the number greater by one than
   the maximum ID number of existing records is specified.
   `vbuf' specifies the pointer to the region of the value.
   `vsiz' specifies the size of the region of the value.  If the size of the value is greater
   than the width tuning parameter of the database, the size is cut down to the width.
   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 tcfdbput(TCFDB *fdb, int64_t id, const void *vbuf, int vsiz);


/* Store a record with a decimal key into a fixed-length database object.
   `fdb' specifies the fixed-length database object connected as a writer.
   `kbuf' specifies the pointer to the region of the decimal key.  It should be more than 0.  If
   it is "min", the minimum ID number of existing records is specified.  If it is "prev", the
   number less by one than the minimum ID number of existing records is specified.  If it is
   "max", the maximum ID number of existing records is specified.  If it is "next", the number
   greater by one than the maximum ID number of existing records is specified.
   `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 the size of the value is greater
   than the width tuning parameter of the database, the size is cut down to the width.
   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 tcfdbput2(TCFDB *fdb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);