git.sur5r.net Git - bacula/bacula/blob - bacula/src/lib/tokyocabinet/tcadb.h

   1 /*************************************************************************************************
   2  * The abstract database API of Tokyo Cabinet
   3  *                                                      Copyright (C) 2006-2008 Mikio Hirabayashi
   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 _TCADB_H                         /* duplication check */
  18 #define _TCADB_H
  19
  20 #if defined(__cplusplus)
  21 #define __TCADB_CLINKAGEBEGIN extern "C" {
  22 #define __TCADB_CLINKAGEEND }
  23 #else
  24 #define __TCADB_CLINKAGEBEGIN
  25 #define __TCADB_CLINKAGEEND
  26 #endif
  27 __TCADB_CLINKAGEBEGIN
  28
  29
  30 #include <stdlib.h>
  31 #include <stdbool.h>
  32 #include <stdint.h>
  33 #include <time.h>
  34 #include <tcutil.h>
  35 #include <tchdb.h>
  36 #include <tcbdb.h>
  37
  38
  39
  40 /*************************************************************************************************
  41  * API
  42  *************************************************************************************************/
  43
  44
  45 typedef struct {                         /* type of structure for an abstract database */
  46   char *name;                            /* name of the database */
  47   TCMDB *mdb;                            /* on-memory database object */
  48   TCHDB *hdb;                            /* hash database object */
  49   TCBDB *bdb;                            /* B+ tree database object */
  50   int64_t capnum;                        /* capacity number of records */
  51   int64_t capsiz;                        /* capacity size of using memory */
  52   uint32_t capcnt;                       /* count for capacity check */
  53   BDBCUR *cur;                           /* cursor of B+ tree */
  54 } TCADB;
  55
  56
  57 /* Create an abstract database object.
  58    The return value is the new abstract database object. */
  59 TCADB *tcadbnew(void);
  60
  61
  62 /* Delete an abstract database object.
  63    `adb' specifies the abstract database object. */
  64 void tcadbdel(TCADB *adb);
  65
  66
  67 /* Open an abstract database.
  68    `adb' specifies the abstract database object.
  69    `name' specifies the name of the database.  If it is "*", the database will be an on-memory
  70    database.  If its suffix is ".tch", the database will be a hash database.  If its suffix is
  71    ".tcb", the database will be a B+ tree database.  Otherwise, this function fails.  Tuning
  72    parameters can trail the name, separated by "#".  Each parameter is composed of the name and
  73    the number, separated by "=".  On-memory database supports "bnum", "capnum", and "capsiz".
  74    Hash database supports "mode", "bnum", "apow", "fpow", "opts", and "rcnum".  B+ tree database
  75    supports "mode", "lmemb", "nmemb", "bnum", "apow", "fpow", "opts", "lcnum", and "ncnum".
  76    "capnum" specifies the capacity number of records.  "capsiz" specifies the capacity size of
  77    using memory.  Records spilled the capacity are removed by the storing order.  "mode" can
  78    contain "w" of writer, "r" of reader, "c" of creating, "t" of truncating, "e" of no locking,
  79    and "f" of non-blocking lock.  The default mode is relevant to "wc".  "opts" can contains "l"
  80    of large option, "d" of Deflate option, and "b" of TCBS option.  For example,
  81    "casket.tch#bnum=1000000#opts=ld" means that the name of the database file is "casket.tch",
  82    and the bucket number is 1000000, and the options are large and Deflate.
  83    If successful, the return value is true, else, it is false. */
  84 bool tcadbopen(TCADB *adb, const char *name);
  85
  86
  87 /* Close an abstract database object.
  88    `adb' specifies the abstract database object.
  89    If successful, the return value is true, else, it is false.
  90    Update of a database is assured to be written when the database is closed.  If a writer opens
  91    a database but does not close it appropriately, the database will be broken. */
  92 bool tcadbclose(TCADB *adb);
  93
  94
  95 /* Store a record into an abstract database object.
  96    `adb' specifies the abstract database object.
  97    `kbuf' specifies the pointer to the region of the key.
  98    `ksiz' specifies the size of the region of the key.
  99    `vbuf' specifies the pointer to the region of the value.
 100    `vsiz' specifies the size of the region of the value.
 101    If successful, the return value is true, else, it is false.
 102    If a record with the same key exists in the database, it is overwritten. */
 103 bool tcadbput(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
 104
 105
 106 /* Store a string record into an abstract object.
 107    `adb' specifies the abstract database object.
 108    `kstr' specifies the string of the key.
 109    `vstr' specifies the string of the value.
 110    If successful, the return value is true, else, it is false.
 111    If a record with the same key exists in the database, it is overwritten. */
 112 bool tcadbput2(TCADB *adb, const char *kstr, const char *vstr);
 113
 114
 115 /* Store a new record into an abstract database object.
 116    `adb' specifies the abstract database object.
 117    `kbuf' specifies the pointer to the region of the key.
 118    `ksiz' specifies the size of the region of the key.
 119    `vbuf' specifies the pointer to the region of the value.
 120    `vsiz' specifies the size of the region of the value.
 121    If successful, the return value is true, else, it is false.
 122    If a record with the same key exists in the database, this function has no effect. */
 123 bool tcadbputkeep(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
 124
 125
 126 /* Store a new string record into an abstract database object.
 127    `adb' specifies the abstract database object.
 128    `kstr' specifies the string of the key.
 129    `vstr' specifies the string of the value.
 130    If successful, the return value is true, else, it is false.
 131    If a record with the same key exists in the database, this function has no effect. */
 132 bool tcadbputkeep2(TCADB *adb, const char *kstr, const char *vstr);
 133
 134
 135 /* Concatenate a value at the end of the existing record in an abstract database object.
 136    `adb' specifies the abstract database object.
 137    `kbuf' specifies the pointer to the region of the key.
 138    `ksiz' specifies the size of the region of the key.
 139    `vbuf' specifies the pointer to the region of the value.
 140    `vsiz' specifies the size of the region of the value.
 141    If successful, the return value is true, else, it is false.
 142    If there is no corresponding record, a new record is created. */
 143 bool tcadbputcat(TCADB *adb, const void *kbuf, int ksiz, const void *vbuf, int vsiz);
 144
 145
 146 /* Concatenate a string value at the end of the existing record in an abstract database object.
 147    `adb' specifies the abstract database object.
 148    `kstr' specifies the string of the key.
 149    `vstr' specifies the string of the value.
 150    If successful, the return value is true, else, it is false.
 151    If there is no corresponding record, a new record is created. */
 152 bool tcadbputcat2(TCADB *adb, const char *kstr, const char *vstr);
 153
 154
 155 /* Remove a record of an abstract database object.
 156    `adb' specifies the abstract database object.
 157    `kbuf' specifies the pointer to the region of the key.
 158    `ksiz' specifies the size of the region of the key.
 159    If successful, the return value is true, else, it is false. */
 160 bool tcadbout(TCADB *adb, const void *kbuf, int ksiz);
 161
 162
 163 /* Remove a string record of an abstract database object.
 164    `adb' specifies the abstract database object.
 165    `kstr' specifies the string of the key.
 166    If successful, the return value is true, else, it is false. */
 167 bool tcadbout2(TCADB *adb, const char *kstr);
 168
 169
 170 /* Retrieve a record in an abstract database object.
 171    `adb' specifies the abstract database object.
 172    `kbuf' specifies the pointer to the region of the key.
 173    `ksiz' specifies the size of the region of the key.
 174    `sp' specifies the pointer to the variable into which the size of the region of the return
 175    value is assigned.
 176    If successful, the return value is the pointer to the region of the value of the corresponding
 177    record.  `NULL' is returned if no record corresponds.
 178    Because an additional zero code is appended at the end of the region of the return value,
 179    the return value can be treated as a character string.  Because the region of the return
 180    value is allocated with the `malloc' call, it should be released with the `free' call when
 181    it is no longer in use. */
 182 void *tcadbget(TCADB *adb, const void *kbuf, int ksiz, int *sp);
 183
 184
 185 /* Retrieve a string record in an abstract database object.
 186    `adb' specifies the abstract database object.
 187    `kstr' specifies the string of the key.
 188    If successful, the return value is the string of the value of the corresponding record.
 189    `NULL' is returned if no record corresponds.
 190    Because the region of the return value is allocated with the `malloc' call, it should be
 191    released with the `free' call when it is no longer in use. */
 192 char *tcadbget2(TCADB *adb, const char *kstr);
 193
 194
 195 /* Get the size of the value of a record in an abstract database object.
 196    `adb' specifies the abstract database object.
 197    `kbuf' specifies the pointer to the region of the key.
 198    `ksiz' specifies the size of the region of the key.
 199    If successful, the return value is the size of the value of the corresponding record, else,
 200    it is -1. */
 201 int tcadbvsiz(TCADB *adb, const void *kbuf, int ksiz);
 202
 203
 204 /* Get the size of the value of a string record in an abstract database object.
 205    `adb' specifies the abstract database object.
 206    `kstr' specifies the string of the key.
 207    If successful, the return value is the size of the value of the corresponding record, else,
 208    it is -1. */
 209 int tcadbvsiz2(TCADB *adb, const char *kstr);
 210
 211
 212 /* Initialize the iterator of an abstract database object.
 213    `adb' specifies the abstract database object.
 214    If successful, the return value is true, else, it is false.
 215    The iterator is used in order to access the key of every record stored in a database. */
 216 bool tcadbiterinit(TCADB *adb);
 217
 218
 219 /* Get the next key of the iterator of an abstract database object.
 220    `adb' specifies the abstract database object.
 221    `sp' specifies the pointer to the variable into which the size of the region of the return
 222    value is assigned.
 223    If successful, the return value is the pointer to the region of the next key, else, it is
 224    `NULL'.  `NULL' is returned when no record is to be get out of the iterator.
 225    Because an additional zero code is appended at the end of the region of the return value, the
 226    return value can be treated as a character string.  Because the region of the return value is
 227    allocated with the `malloc' call, it should be released with the `free' call when it is no
 228    longer in use.  It is possible to access every record by iteration of calling this function.
 229    It is allowed to update or remove records whose keys are fetched while the iteration.
 230    However, it is not assured if updating the database is occurred while the iteration.  Besides,
 231    the order of this traversal access method is arbitrary, so it is not assured that the order of
 232    storing matches the one of the traversal access. */
 233 void *tcadbiternext(TCADB *adb, int *sp);
 234
 235
 236 /* Get the next key string of the iterator of an abstract database object.
 237    `adb' specifies the abstract database object.
 238    If successful, the return value is the string of the next key, else, it is `NULL'.  `NULL' is
 239    returned when no record is to be get out of the iterator.
 240    Because the region of the return value is allocated with the `malloc' call, it should be
 241    released with the `free' call when it is no longer in use.  It is possible to access every
 242    record by iteration of calling this function.  However, it is not assured if updating the
 243    database is occurred while the iteration.  Besides, the order of this traversal access method
 244    is arbitrary, so it is not assured that the order of storing matches the one of the traversal
 245    access. */
 246 char *tcadbiternext2(TCADB *adb);
 247
 248
 249 /* Get forward matching keys in an abstract database object.
 250    `adb' specifies the abstract database object.
 251    `pbuf' specifies the pointer to the region of the prefix.
 252    `psiz' specifies the size of the region of the prefix.
 253    `max' specifies the maximum number of keys to be fetched.  If it is negative, no limit is
 254    specified.
 255    The return value is a list object of the corresponding keys.  This function does never fail
 256    and return an empty list even if no key corresponds.
 257    Because the object of the return value is created with the function `tclistnew', it should be
 258    deleted with the function `tclistdel' when it is no longer in use.  Note that this function
 259    may be very slow because every key in the database is scanned. */
 260 TCLIST *tcadbfwmkeys(TCADB *adb, const void *pbuf, int psiz, int max);
 261
 262
 263 /* Get forward matching string keys in an abstract database object.
 264    `adb' specifies the abstract database object.
 265    `pstr' specifies the string of the prefix.
 266    `max' specifies the maximum number of keys to be fetched.  If it is negative, no limit is
 267    specified.
 268    The return value is a list object of the corresponding keys.  This function does never fail
 269    and return an empty list even if no key corresponds.
 270    Because the object of the return value is created with the function `tclistnew', it should be
 271    deleted with the function `tclistdel' when it is no longer in use.  Note that this function
 272    may be very slow because every key in the database is scanned. */
 273 TCLIST *tcadbfwmkeys2(TCADB *adb, const char *pstr, int max);
 274
 275
 276 /* Synchronize updated contents of an abstract database object with the file and the device.
 277    `adb' specifies the abstract database object.
 278    If successful, the return value is true, else, it is false.
 279    This function fails and has no effect for on-memory database. */
 280 bool tcadbsync(TCADB *adb);
 281
 282
 283 /* Remove all records of an abstract database object.
 284    `adb' specifies the abstract database object.
 285    If successful, the return value is true, else, it is false. */
 286 bool tcadbvanish(TCADB *adb);
 287
 288
 289 /* Copy the database file of an abstract database object.
 290    `adb' specifies the abstract database object.
 291    `path' specifies the path of the destination file.  If it begins with `@', the trailing
 292    substring is executed as a command line.
 293    If successful, the return value is true, else, it is false.  False is returned if the executed
 294    command returns non-zero code.
 295    The database file is assured to be kept synchronized and not modified while the copying or
 296    executing operation is in progress.  So, this function is useful to create a backup file of
 297    the database file.  This function fails and has no effect for on-memory database. */
 298 bool tcadbcopy(TCADB *adb, const char *path);
 299
 300
 301 /* Get the number of records of an abstract database object.
 302    `adb' specifies the abstract database object.
 303    The return value is the number of records or 0 if the object does not connect to any database
 304    instance. */
 305 uint64_t tcadbrnum(TCADB *adb);
 306
 307
 308 /* Get the size of the database of an abstract database object.
 309    `adb' specifies the abstract database object.
 310    The return value is the size of the database or 0 if the object does not connect to any
 311    database instance. */
 312 uint64_t tcadbsize(TCADB *adb);
 313
 314
 315
 316 __TCADB_CLINKAGEEND
 317 #endif                                   /* duplication check */
 318
 319
 320 /* END OF FILE */