tctdb.h

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

   It is allowed to update or remove records whose keys are fetched while the iteration.
   However, it is not assured if updating the database is occurred while the iteration.  Besides,
   the order of this traversal access method is arbitrary, so it is not assured that the order of
   storing matches the one of the traversal access. */
void *tctdbiternext(TCTDB *tdb, int *sp);


/* Get the next primary key string of the iterator of a table database object.
   `tdb' specifies the table database object.
   If successful, the return value is the string of the next primary key, else, it is `NULL'.
   `NULL' is returned when no record is to be get out of the iterator.
   Because the region of the return value is allocated with the `malloc' call, it should be
   released with the `free' call when it is no longer in use.  It is possible to access every
   record by iteration of calling this function.  However, it is not assured if updating the
   database is occurred while the iteration.  Besides, the order of this traversal access method
   is arbitrary, so it is not assured that the order of storing matches the one of the traversal
   access. */
char *tctdbiternext2(TCTDB *tdb);


/* Get forward matching primary keys in a table database object.
   `tdb' specifies the table database object.
   `pbuf' specifies the pointer to the region of the prefix.
   `psiz' specifies the size of the region of the prefix.
   `max' specifies the maximum number of keys to be fetched.  If it is negative, no limit is
   specified.
   The return value is a list object of the corresponding keys.  This function does never fail
   and return an empty list even if no key corresponds.
   Because the object of the return value is created with the function `tclistnew', it should be
   deleted with the function `tclistdel' when it is no longer in use.  Note that this function
   may be very slow because every key in the database is scanned. */
TCLIST *tctdbfwmkeys(TCTDB *tdb, const void *pbuf, int psiz, int max);


/* Get forward matching string primary keys in a table database object.
   `tdb' specifies the table database object.
   `pstr' specifies the string of the prefix.
   `max' specifies the maximum number of keys to be fetched.  If it is negative, no limit is
   specified.
   The return value is a list object of the corresponding keys.  This function does never fail
   and return an empty list even if no key corresponds.
   Because the object of the return value is created with the function `tclistnew', it should be
   deleted with the function `tclistdel' when it is no longer in use.  Note that this function
   may be very slow because every key in the database is scanned. */
TCLIST *tctdbfwmkeys2(TCTDB *tdb, const char *pstr, int max);


/* Add an integer to a column of a record in a table database object.
   `tdb' specifies the table database object connected as a writer.
   `kbuf' specifies the pointer to the region of the primary key.
   `ksiz' specifies the size of the region of the primary key.
   `num' specifies the additional value.
   If successful, the return value is the summation value, else, it is `INT_MIN'.
   The additional value is stored as a decimal string value of a column whose name is "_num".
   If no record corresponds, a new record with the additional value is stored. */
int tctdbaddint(TCTDB *tdb, const void *pkbuf, int pksiz, int num);


/* Add a real number to a column of a record in a table database object.
   `tdb' specifies the table database object connected as a writer.
   `kbuf' specifies the pointer to the region of the primary key.
   `ksiz' specifies the size of the region of the primary key.
   `num' specifies the additional value.
   If successful, the return value is the summation value, else, it is Not-a-Number.
   The additional value is stored as a decimal string value of a column whose name is "_num".
   If no record corresponds, a new record with the additional value is stored. */
double tctdbadddouble(TCTDB *tdb, const void *pkbuf, int pksiz, double num);


/* Synchronize updated contents of a table database object with the file and the device.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false.
   This function is useful when another process connects to the same database file. */
bool tctdbsync(TCTDB *tdb);


/* Optimize the file of a table database object.
   `tdb' specifies the table database object connected as a writer.
   `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 two times of the number of records.
   `apow' specifies the size of record alignment by power of 2.  If it is negative, the current
   setting is not changed.
   `fpow' specifies the maximum number of elements of the free block pool by power of 2.  If it
   is negative, the current setting is not changed.
   `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 record
   is compressed with Deflate encoding, `BDBTBZIP' specifies that each record is compressed with
   BZIP2 encoding, `BDBTTCBS' specifies that each record is compressed with TCBS encoding.  If it
   is `UINT8_MAX', the current setting is not changed.
   If successful, the return value is true, else, it is false.
   This function is useful to reduce the size of the database file with data fragmentation by
   successive updating. */
bool tctdboptimize(TCTDB *tdb, int64_t bnum, int8_t apow, int8_t fpow, uint8_t opts);


/* Remove all records of a table database object.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false. */
bool tctdbvanish(TCTDB *tdb);


/* Copy the database file of a table database object.
   `tdb' specifies the table database object.
   `path' specifies the path of the destination file.  If it begins with `@', the trailing
   substring is executed as a command line.
   If successful, the return value is true, else, it is false.  False is returned if the executed
   command returns non-zero code.
   The database file is assured to be kept synchronized and not modified while the copying or
   executing operation is in progress.  So, this function is useful to create a backup file of
   the database file. */
bool tctdbcopy(TCTDB *tdb, const char *path);


/* Begin the transaction of a table database object.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false.
   The database is locked by the thread while the transaction so that only one transaction can be
   activated with a database object at the same time.  Thus, the serializable isolation level is
   assumed if every database operation is performed in the transaction.  Because all pages are
   cached on memory while the transaction, the amount of referred records is limited by the
   memory capacity.  If the database is closed during transaction, the transaction is aborted
   implicitly. */
bool tctdbtranbegin(TCTDB *tdb);


/* Commit the transaction of a table database object.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false.
   Update in the transaction is fixed when it is committed successfully. */
bool tctdbtrancommit(TCTDB *tdb);


/* Abort the transaction of a table database object.
   `tdb' specifies the table database object connected as a writer.
   If successful, the return value is true, else, it is false.
   Update in the transaction is discarded when it is aborted.  The state of the database is
   rollbacked to before transaction. */
bool tctdbtranabort(TCTDB *tdb);


/* Get the file path of a table database object.
   `tdb' specifies the table database object.
   The return value is the path of the database file or `NULL' if the object does not connect to
   any database file. */
const char *tctdbpath(TCTDB *tdb);


/* Get the number of records ccccof a table database object.
   `tdb' specifies the table database object.
   The return value is the number of records or 0 if the object does not connect to any database
   file. */
uint64_t tctdbrnum(TCTDB *tdb);


/* Get the size of the database file of a table database object.
   `tdb' specifies the table database object.
   The return value is the size of the database file or 0 if the object does not connect to any
   database file. */
uint64_t tctdbfsiz(TCTDB *tdb);


/* Set a column index to a table database object.
   `tdb' specifies the table database object connected as a writer.
   `name' specifies the name of a column.  If the name of an existing index is specified, the
   index is rebuilt.  An empty string means the primary key.
   `type' specifies the index type: `TDBITLEXICAL' for lexical string, `TDBITDECIMAL' for decimal
   string.  If it is `TDBITOPT', the index is optimized.  If it is `TDBITVOID', the index is
   removed.  If `TDBITKEEP' is added by bitwise-or and the index exists, this function merely
   returns failure.
   If successful, the return value is true, else, it is false.
   Note that the setting indices should be set after the database is opened. */
bool tctdbsetindex(TCTDB *tdb, const char *name, int type);


/* Generate a unique ID number of a table database object.
   `tdb' specifies the table database object connected as a writer.
   The return value is the new unique ID number or -1 on failure. */
int64_t tctdbgenuid(TCTDB *tdb);


/* Create a query object.
   `tdb' specifies the table database object.
   The return value is the new query object. */
TDBQRY *tctdbqrynew(TCTDB *tdb);


/* Delete a query object.
   `qry' specifies the query object. */
void tctdbqrydel(TDBQRY *qry);


/* Add a narrowing condition to a query object.
   `qry' specifies the query object.
   `name' specifies the name of a column.  An empty string means the primary key.
   `op' specifies an operation type: `TDBQCSTREQ' for string which is equal to the expression,
   `TDBQCSTRINC' for string which is included in the expression, `TDBQCSTRBW' for string which
   begins with the expression, `TDBQCSTREW' for string which ends with the expression,
   `TDBQCSTRAND' for string which includes all tokens in the expression, `TDBQCSTROR' for string
   which includes at least one token in the expression, `TDBQCSTROREQ' for string which is equal
   to at least one token in the expression, `TDBQCSTRRX' for string which matches regular
   expressions of the expression, `TDBQCNUMEQ' for number which is equal to the expression,
   `TDBQCNUMGT' for number which is greater than the expression, `TDBQCNUMGE' for number which is
   greater than or equal to the expression, `TDBQCNUMLT' for number which is less than the
   expression, `TDBQCNUMLE' for number which is less than or equal to the expression, `TDBQCNUMBT'
   for number which is between two tokens of the expression, `TDBQCNUMOREQ' for number which is
   equal to at least one token in the expression.  All operations can be flagged by bitwise-or:
   `TDBQCNEGATE' for negation, `TDBQCNOIDX' for using no index.
   `expr' specifies an operand exression. */
void tctdbqryaddcond(TDBQRY *qry, const char *name, int op, const char *expr);


/* Set the order of a query object.
   `qry' specifies the query object.
   `name' specifies the name of a column.  An empty string means the primary key.
   `type' specifies the order type: `TDBQOSTRASC' for string ascending, `TDBQOSTRDESC' for
   string descending, `TDBQONUMASC' for number ascending, `TDBQONUMDESC' for number descending. */
void tctdbqrysetorder(TDBQRY *qry, const char *name, int type);


/* Set the limit number of records of the result of a query object.
   `qry' specifies the query object.
   `max' specifies the maximum number of records of the result.  If it is negative, no limit is
   specified.
   `skip' specifies the number of skipped records of the result.  If it is not more than 0, no