ext/lsm1/lsm.h

   1 /*
   2 ** 2011-08-10
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 **
  13 ** This file defines the LSM API.
  14 */
  15 #ifndef _LSM_H
  16 #define _LSM_H
  17 #include <stddef.h>
  18 #ifdef __cplusplus
  19 extern "C" {
  20 #endif
  21
  22 /*
  23 ** Opaque handle types.
  24 */
  25 typedef struct lsm_compress lsm_compress;   /* Compression library functions */
  26 typedef struct lsm_compress_factory lsm_compress_factory;
  27 typedef struct lsm_cursor lsm_cursor;       /* Database cursor handle */
  28 typedef struct lsm_db lsm_db;               /* Database connection handle */
  29 typedef struct lsm_env lsm_env;             /* Runtime environment */
  30 typedef struct lsm_file lsm_file;           /* OS file handle */
  31 typedef struct lsm_mutex lsm_mutex;         /* Mutex handle */
  32
  33 /* 64-bit integer type used for file offsets. */
  34 typedef long long int lsm_i64;              /* 64-bit signed integer type */
  35
  36 /* Candidate values for the 3rd argument to lsm_env.xLock() */
  37 #define LSM_LOCK_UNLOCK 0
  38 #define LSM_LOCK_SHARED 1
  39 #define LSM_LOCK_EXCL   2
  40
  41 /* Flags for lsm_env.xOpen() */
  42 #define LSM_OPEN_READONLY 0x0001
  43
  44 /*
  45 ** CAPI: Database Runtime Environment
  46 **
  47 ** Run-time environment used by LSM
  48 */
  49 struct lsm_env {
  50   int nByte;                 /* Size of this structure in bytes */
  51   int iVersion;              /* Version number of this structure (1) */
  52   /****** file i/o ***********************************************/
  53   void *pVfsCtx;
  54   int (*xFullpath)(lsm_env*, const char *, char *, int *);
  55   int (*xOpen)(lsm_env*, const char *, int flags, lsm_file **);
  56   int (*xRead)(lsm_file *, lsm_i64, void *, int);
  57   int (*xWrite)(lsm_file *, lsm_i64, void *, int);
  58   int (*xTruncate)(lsm_file *, lsm_i64);
  59   int (*xSync)(lsm_file *);
  60   int (*xSectorSize)(lsm_file *);
  61   int (*xRemap)(lsm_file *, lsm_i64, void **, lsm_i64*);
  62   int (*xFileid)(lsm_file *, void *pBuf, int *pnBuf);
  63   int (*xClose)(lsm_file *);
  64   int (*xUnlink)(lsm_env*, const char *);
  65   int (*xLock)(lsm_file*, int, int);
  66   int (*xTestLock)(lsm_file*, int, int, int);
  67   int (*xShmMap)(lsm_file*, int, int, void **);
  68   void (*xShmBarrier)(void);
  69   int (*xShmUnmap)(lsm_file*, int);
  70   /****** memory allocation ****************************************/
  71   void *pMemCtx;
  72   void *(*xMalloc)(lsm_env*, size_t);            /* malloc(3) function */
  73   void *(*xRealloc)(lsm_env*, void *, size_t);   /* realloc(3) function */
  74   void (*xFree)(lsm_env*, void *);               /* free(3) function */
  75   size_t (*xSize)(lsm_env*, void *);             /* xSize function */
  76   /****** mutexes ****************************************************/
  77   void *pMutexCtx;
  78   int (*xMutexStatic)(lsm_env*,int,lsm_mutex**); /* Obtain a static mutex */
  79   int (*xMutexNew)(lsm_env*, lsm_mutex**);       /* Get a new dynamic mutex */
  80   void (*xMutexDel)(lsm_mutex *);           /* Delete an allocated mutex */
  81   void (*xMutexEnter)(lsm_mutex *);         /* Grab a mutex */
  82   int (*xMutexTry)(lsm_mutex *);            /* Attempt to obtain a mutex */
  83   void (*xMutexLeave)(lsm_mutex *);         /* Leave a mutex */
  84   int (*xMutexHeld)(lsm_mutex *);           /* Return true if mutex is held */
  85   int (*xMutexNotHeld)(lsm_mutex *);        /* Return true if mutex not held */
  86   /****** other ****************************************************/
  87   int (*xSleep)(lsm_env*, int microseconds);
  88
  89   /* New fields may be added in future releases, in which case the
  90   ** iVersion value will increase. */
  91 };
  92
  93 /*
  94 ** Values that may be passed as the second argument to xMutexStatic.
  95 */
  96 #define LSM_MUTEX_GLOBAL 1
  97 #define LSM_MUTEX_HEAP   2
  98
  99 /*
 100 ** CAPI: LSM Error Codes
 101 */
 102 #define LSM_OK         0
 103 #define LSM_ERROR      1
 104 #define LSM_BUSY       5
 105 #define LSM_NOMEM      7
 106 #define LSM_READONLY   8
 107 #define LSM_IOERR     10
 108 #define LSM_CORRUPT   11
 109 #define LSM_FULL      13
 110 #define LSM_CANTOPEN  14
 111 #define LSM_PROTOCOL  15
 112 #define LSM_MISUSE    21
 113
 114 #define LSM_MISMATCH  50
 115
 116
 117 #define LSM_IOERR_NOENT (LSM_IOERR | (1<<8))
 118
 119 /*
 120 ** CAPI: Creating and Destroying Database Connection Handles
 121 **
 122 ** Open and close a database connection handle.
 123 */
 124 int lsm_new(lsm_env*, lsm_db **ppDb);
 125 int lsm_close(lsm_db *pDb);
 126
 127 /*
 128 ** CAPI: Connecting to a Database
 129 */
 130 int lsm_open(lsm_db *pDb, const char *zFilename);
 131
 132 /*
 133 ** CAPI: Obtaining pointers to database environments
 134 **
 135 ** Return a pointer to the environment used by the database connection
 136 ** passed as the first argument. Assuming the argument is valid, this
 137 ** function always returns a valid environment pointer - it cannot fail.
 138 */
 139 lsm_env *lsm_get_env(lsm_db *pDb);
 140
 141 /*
 142 ** The lsm_default_env() function returns a pointer to the default LSM
 143 ** environment for the current platform.
 144 */
 145 lsm_env *lsm_default_env(void);
 146
 147
 148 /*
 149 ** CAPI: Configuring a database connection.
 150 **
 151 ** The lsm_config() function is used to configure a database connection.
 152 */
 153 int lsm_config(lsm_db *, int, ...);
 154
 155 /*
 156 ** The following values may be passed as the second argument to lsm_config().
 157 **
 158 ** LSM_CONFIG_AUTOFLUSH:
 159 **   A read/write integer parameter.
 160 **
 161 **   This value determines the amount of data allowed to accumulate in a
 162 **   live in-memory tree before it is marked as old. After committing a
 163 **   transaction, a connection checks if the size of the live in-memory tree,
 164 **   including data structure overhead, is greater than the value of this
 165 **   option in KB. If it is, and there is not already an old in-memory tree,
 166 **   the live in-memory tree is marked as old.
 167 **
 168 **   The maximum allowable value is 1048576 (1GB). There is no minimum
 169 **   value. If this parameter is set to zero, then an attempt is made to
 170 **   mark the live in-memory tree as old after each transaction is committed.
 171 **
 172 **   The default value is 1024 (1MB).
 173 **
 174 ** LSM_CONFIG_PAGE_SIZE:
 175 **   A read/write integer parameter. This parameter may only be set before
 176 **   lsm_open() has been called.
 177 **
 178 ** LSM_CONFIG_BLOCK_SIZE:
 179 **   A read/write integer parameter.
 180 **
 181 **   This parameter may only be set before lsm_open() has been called. It
 182 **   must be set to a power of two between 64 and 65536, inclusive (block
 183 **   sizes between 64KB and 64MB).
 184 **
 185 **   If the connection creates a new database, the block size of the new
 186 **   database is set to the value of this option in KB. After lsm_open()
 187 **   has been called, querying this parameter returns the actual block
 188 **   size of the opened database.
 189 **
 190 **   The default value is 1024 (1MB blocks).
 191 **
 192 ** LSM_CONFIG_SAFETY:
 193 **   A read/write integer parameter. Valid values are 0, 1 (the default)
 194 **   and 2. This parameter determines how robust the database is in the
 195 **   face of a system crash (e.g. a power failure or operating system
 196 **   crash). As follows:
 197 **
 198 **     0 (off):    No robustness. A system crash may corrupt the database.
 199 **
 200 **     1 (normal): Some robustness. A system crash may not corrupt the
 201 **                 database file, but recently committed transactions may
 202 **                 be lost following recovery.
 203 **
 204 **     2 (full):   Full robustness. A system crash may not corrupt the
 205 **                 database file. Following recovery the database file
 206 **                 contains all successfully committed transactions.
 207 **
 208 ** LSM_CONFIG_AUTOWORK:
 209 **   A read/write integer parameter.
 210 **
 211 ** LSM_CONFIG_AUTOCHECKPOINT:
 212 **   A read/write integer parameter.
 213 **
 214 **   If this option is set to non-zero value N, then a checkpoint is
 215 **   automatically attempted after each N KB of data have been written to
 216 **   the database file.
 217 **
 218 **   The amount of uncheckpointed data already written to the database file
 219 **   is a global parameter. After performing database work (writing to the
 220 **   database file), the process checks if the total amount of uncheckpointed
 221 **   data exceeds the value of this paramter. If so, a checkpoint is performed.
 222 **   This means that this option may cause the connection to perform a
 223 **   checkpoint even if the current connection has itself written very little
 224 **   data into the database file.
 225 **
 226 **   The default value is 2048 (checkpoint every 2MB).
 227 **
 228 ** LSM_CONFIG_MMAP:
 229 **   A read/write integer parameter. If this value is set to 0, then the
 230 **   database file is accessed using ordinary read/write IO functions. Or,
 231 **   if it is set to 1, then the database file is memory mapped and accessed
 232 **   that way. If this parameter is set to any value N greater than 1, then
 233 **   up to the first N KB of the file are memory mapped, and any remainder
 234 **   accessed using read/write IO.
 235 **
 236 **   The default value is 1 on 64-bit platforms and 32768 on 32-bit platforms.
 237 **
 238 **
 239 ** LSM_CONFIG_USE_LOG:
 240 **   A read/write boolean parameter. True (the default) to use the log
 241 **   file normally. False otherwise.
 242 **
 243 ** LSM_CONFIG_AUTOMERGE:
 244 **   A read/write integer parameter. The minimum number of segments to
 245 **   merge together at a time. Default value 4.
 246 **
 247 ** LSM_CONFIG_MAX_FREELIST:
 248 **   A read/write integer parameter. The maximum number of free-list
 249 **   entries that are stored in a database checkpoint (the others are
 250 **   stored elsewhere in the database).
 251 **
 252 **   There is no reason for an application to configure or query this
 253 **   parameter. It is only present because configuring a small value
 254 **   makes certain parts of the lsm code easier to test.
 255 **
 256 ** LSM_CONFIG_MULTIPLE_PROCESSES:
 257 **   A read/write boolean parameter. This parameter may only be set before
 258 **   lsm_open() has been called. If true, the library uses shared-memory
 259 **   and posix advisory locks to co-ordinate access by clients from within
 260 **   multiple processes. Otherwise, if false, all database clients must be
 261 **   located in the same process. The default value is true.
 262 **
 263 ** LSM_CONFIG_SET_COMPRESSION:
 264 **   Set the compression methods used to compress and decompress database
 265 **   content. The argument to this option should be a pointer to a structure
 266 **   of type lsm_compress. The lsm_config() method takes a copy of the
 267 **   structures contents.
 268 **
 269 **   This option may only be used before lsm_open() is called. Invoking it
 270 **   after lsm_open() has been called results in an LSM_MISUSE error.
 271 **
 272 ** LSM_CONFIG_GET_COMPRESSION:
 273 **   Query the compression methods used to compress and decompress database
 274 **   content.
 275 **
 276 ** LSM_CONFIG_SET_COMPRESSION_FACTORY:
 277 **   Configure a factory method to be invoked in case of an LSM_MISMATCH
 278 **   error.
 279 **
 280 ** LSM_CONFIG_READONLY:
 281 **   A read/write boolean parameter. This parameter may only be set before
 282 **   lsm_open() is called.
 283 */
 284 #define LSM_CONFIG_AUTOFLUSH                1
 285 #define LSM_CONFIG_PAGE_SIZE                2
 286 #define LSM_CONFIG_SAFETY                   3
 287 #define LSM_CONFIG_BLOCK_SIZE               4
 288 #define LSM_CONFIG_AUTOWORK                 5
 289 #define LSM_CONFIG_MMAP                     7
 290 #define LSM_CONFIG_USE_LOG                  8
 291 #define LSM_CONFIG_AUTOMERGE                9
 292 #define LSM_CONFIG_MAX_FREELIST            10
 293 #define LSM_CONFIG_MULTIPLE_PROCESSES      11
 294 #define LSM_CONFIG_AUTOCHECKPOINT          12
 295 #define LSM_CONFIG_SET_COMPRESSION         13
 296 #define LSM_CONFIG_GET_COMPRESSION         14
 297 #define LSM_CONFIG_SET_COMPRESSION_FACTORY 15
 298 #define LSM_CONFIG_READONLY                16
 299
 300 #define LSM_SAFETY_OFF    0
 301 #define LSM_SAFETY_NORMAL 1
 302 #define LSM_SAFETY_FULL   2
 303
 304 /*
 305 ** CAPI: Compression and/or Encryption Hooks
 306 */
 307 struct lsm_compress {
 308   void *pCtx;
 309   unsigned int iId;
 310   int (*xBound)(void *, int nSrc);
 311   int (*xCompress)(void *, char *, int *, const char *, int);
 312   int (*xUncompress)(void *, char *, int *, const char *, int);
 313   void (*xFree)(void *pCtx);
 314 };
 315
 316 struct lsm_compress_factory {
 317   void *pCtx;
 318   int (*xFactory)(void *, lsm_db *, unsigned int);
 319   void (*xFree)(void *pCtx);
 320 };
 321
 322 #define LSM_COMPRESSION_EMPTY 0
 323 #define LSM_COMPRESSION_NONE  1
 324
 325 /*
 326 ** CAPI: Allocating and Freeing Memory
 327 **
 328 ** Invoke the memory allocation functions that belong to environment
 329 ** pEnv. Or the system defaults if no memory allocation functions have
 330 ** been registered.
 331 */
 332 void *lsm_malloc(lsm_env*, size_t);
 333 void *lsm_realloc(lsm_env*, void *, size_t);
 334 void lsm_free(lsm_env*, void *);
 335
 336 /*
 337 ** CAPI: Querying a Connection For Operational Data
 338 **
 339 ** Query a database connection for operational statistics or data.
 340 */
 341 int lsm_info(lsm_db *, int, ...);
 342
 343 int lsm_get_user_version(lsm_db *, unsigned int *);
 344 int lsm_set_user_version(lsm_db *, unsigned int);
 345
 346 /*
 347 ** The following values may be passed as the second argument to lsm_info().
 348 **
 349 ** LSM_INFO_NWRITE:
 350 **   The third parameter should be of type (int *). The location pointed
 351 **   to by the third parameter is set to the number of 4KB pages written to
 352 **   the database file during the lifetime of this connection.
 353 **
 354 ** LSM_INFO_NREAD:
 355 **   The third parameter should be of type (int *). The location pointed
 356 **   to by the third parameter is set to the number of 4KB pages read from
 357 **   the database file during the lifetime of this connection.
 358 **
 359 ** LSM_INFO_DB_STRUCTURE:
 360 **   The third argument should be of type (char **). The location pointed
 361 **   to is populated with a pointer to a nul-terminated string containing
 362 **   the string representation of a Tcl data-structure reflecting the
 363 **   current structure of the database file. Specifically, the current state
 364 **   of the worker snapshot. The returned string should be eventually freed
 365 **   by the caller using lsm_free().
 366 **
 367 **   The returned list contains one element for each level in the database,
 368 **   in order from most to least recent. Each element contains a
 369 **   single element for each segment comprising the corresponding level,
 370 **   starting with the lhs segment, then each of the rhs segments (if any)
 371 **   in order from most to least recent.
 372 **
 373 **   Each segment element is itself a list of 4 integer values, as follows:
 374 **
 375 **   <ol><li> First page of segment
 376 **       <li> Last page of segment
 377 **       <li> Root page of segment (if applicable)
 378 **       <li> Total number of pages in segment
 379 **   </ol>
 380 **
 381 ** LSM_INFO_ARRAY_STRUCTURE:
 382 **   There should be two arguments passed following this option (i.e. a
 383 **   total of four arguments passed to lsm_info()). The first argument
 384 **   should be the page number of the first page in a database array
 385 **   (perhaps obtained from an earlier INFO_DB_STRUCTURE call). The second
 386 **   trailing argument should be of type (char **). The location pointed
 387 **   to is populated with a pointer to a nul-terminated string that must
 388 **   be eventually freed using lsm_free() by the caller.
 389 **
 390 **   The output string contains the text representation of a Tcl list of
 391 **   integers. Each pair of integers represent a range of pages used by
 392 **   the identified array. For example, if the array occupies database
 393 **   pages 993 to 1024, then pages 2048 to 2777, then the returned string
 394 **   will be "993 1024 2048 2777".
 395 **
 396 **   If the specified integer argument does not correspond to the first
 397 **   page of any database array, LSM_ERROR is returned and the output
 398 **   pointer is set to a NULL value.
 399 **
 400 ** LSM_INFO_LOG_STRUCTURE:
 401 **   The third argument should be of type (char **). The location pointed
 402 **   to is populated with a pointer to a nul-terminated string containing
 403 **   the string representation of a Tcl data-structure. The returned
 404 **   string should be eventually freed by the caller using lsm_free().
 405 **
 406 **   The Tcl structure returned is a list of six integers that describe
 407 **   the current structure of the log file.
 408 **
 409 ** LSM_INFO_ARRAY_PAGES:
 410 **
 411 ** LSM_INFO_PAGE_ASCII_DUMP:
 412 **   As with LSM_INFO_ARRAY_STRUCTURE, there should be two arguments passed
 413 **   with calls that specify this option - an integer page number and a
 414 **   (char **) used to return a nul-terminated string that must be later
 415 **   freed using lsm_free(). In this case the output string is populated
 416 **   with a human-readable description of the page content.
 417 **
 418 **   If the page cannot be decoded, it is not an error. In this case the
 419 **   human-readable output message will report the systems failure to
 420 **   interpret the page data.
 421 **
 422 ** LSM_INFO_PAGE_HEX_DUMP:
 423 **   This argument is similar to PAGE_ASCII_DUMP, except that keys and
 424 **   values are represented using hexadecimal notation instead of ascii.
 425 **
 426 ** LSM_INFO_FREELIST:
 427 **   The third argument should be of type (char **). The location pointed
 428 **   to is populated with a pointer to a nul-terminated string containing
 429 **   the string representation of a Tcl data-structure. The returned
 430 **   string should be eventually freed by the caller using lsm_free().
 431 **
 432 **   The Tcl structure returned is a list containing one element for each
 433 **   free block in the database. The element itself consists of two
 434 **   integers - the block number and the id of the snapshot that freed it.
 435 **
 436 ** LSM_INFO_CHECKPOINT_SIZE:
 437 **   The third argument should be of type (int *). The location pointed to
 438 **   by this argument is populated with the number of KB written to the
 439 **   database file since the most recent checkpoint.
 440 **
 441 ** LSM_INFO_TREE_SIZE:
 442 **   If this value is passed as the second argument to an lsm_info() call, it
 443 **   should be followed by two arguments of type (int *) (for a total of four
 444 **   arguments).
 445 **
 446 **   At any time, there are either one or two tree structures held in shared
 447 **   memory that new database clients will access (there may also be additional
 448 **   tree structures being used by older clients - this API does not provide
 449 **   information on them). One tree structure - the current tree - is used to
 450 **   accumulate new data written to the database. The other tree structure -
 451 **   the old tree - is a read-only tree holding older data and may be flushed
 452 **   to disk at any time.
 453 **
 454 **   Assuming no error occurs, the location pointed to by the first of the two
 455 **   (int *) arguments is set to the size of the old in-memory tree in KB.
 456 **   The second is set to the size of the current, or live in-memory tree.
 457 **
 458 ** LSM_INFO_COMPRESSION_ID:
 459 **   This value should be followed by a single argument of type
 460 **   (unsigned int *). If successful, the location pointed to is populated
 461 **   with the database compression id before returning.
 462 */
 463 #define LSM_INFO_NWRITE           1
 464 #define LSM_INFO_NREAD            2
 465 #define LSM_INFO_DB_STRUCTURE     3
 466 #define LSM_INFO_LOG_STRUCTURE    4
 467 #define LSM_INFO_ARRAY_STRUCTURE  5
 468 #define LSM_INFO_PAGE_ASCII_DUMP  6
 469 #define LSM_INFO_PAGE_HEX_DUMP    7
 470 #define LSM_INFO_FREELIST         8
 471 #define LSM_INFO_ARRAY_PAGES      9
 472 #define LSM_INFO_CHECKPOINT_SIZE 10
 473 #define LSM_INFO_TREE_SIZE       11
 474 #define LSM_INFO_FREELIST_SIZE   12
 475 #define LSM_INFO_COMPRESSION_ID  13
 476
 477
 478 /*
 479 ** CAPI: Opening and Closing Write Transactions
 480 **
 481 ** These functions are used to open and close transactions and nested
 482 ** sub-transactions.
 483 **
 484 ** The lsm_begin() function is used to open transactions and sub-transactions.
 485 ** A successful call to lsm_begin() ensures that there are at least iLevel
 486 ** nested transactions open. To open a top-level transaction, pass iLevel=1.
 487 ** To open a sub-transaction within the top-level transaction, iLevel=2.
 488 ** Passing iLevel=0 is a no-op.
 489 **
 490 ** lsm_commit() is used to commit transactions and sub-transactions. A
 491 ** successful call to lsm_commit() ensures that there are at most iLevel
 492 ** nested transactions open. To commit a top-level transaction, pass iLevel=0.
 493 ** To commit all sub-transactions inside the main transaction, pass iLevel=1.
 494 **
 495 ** Function lsm_rollback() is used to roll back transactions and
 496 ** sub-transactions. A successful call to lsm_rollback() restores the database
 497 ** to the state it was in when the iLevel'th nested sub-transaction (if any)
 498 ** was first opened. And then closes transactions to ensure that there are
 499 ** at most iLevel nested transactions open. Passing iLevel=0 rolls back and
 500 ** closes the top-level transaction. iLevel=1 also rolls back the top-level
 501 ** transaction, but leaves it open. iLevel=2 rolls back the sub-transaction
 502 ** nested directly inside the top-level transaction (and leaves it open).
 503 */
 504 int lsm_begin(lsm_db *pDb, int iLevel);
 505 int lsm_commit(lsm_db *pDb, int iLevel);
 506 int lsm_rollback(lsm_db *pDb, int iLevel);
 507
 508 /*
 509 ** CAPI: Writing to a Database
 510 **
 511 ** Write a new value into the database. If a value with a duplicate key
 512 ** already exists it is replaced.
 513 */
 514 int lsm_insert(lsm_db*, const void *pKey, int nKey, const void *pVal, int nVal);
 515
 516 /*
 517 ** Delete a value from the database. No error is returned if the specified
 518 ** key value does not exist in the database.
 519 */
 520 int lsm_delete(lsm_db *, const void *pKey, int nKey);
 521
 522 /*
 523 ** Delete all database entries with keys that are greater than (pKey1/nKey1)
 524 ** and smaller than (pKey2/nKey2). Note that keys (pKey1/nKey1) and
 525 ** (pKey2/nKey2) themselves, if they exist in the database, are not deleted.
 526 **
 527 ** Return LSM_OK if successful, or an LSM error code otherwise.
 528 */
 529 int lsm_delete_range(lsm_db *,
 530     const void *pKey1, int nKey1, const void *pKey2, int nKey2
 531 );
 532
 533 /*
 534 ** CAPI: Explicit Database Work and Checkpointing
 535 **
 536 ** This function is called by a thread to work on the database structure.
 537 */
 538 int lsm_work(lsm_db *pDb, int nMerge, int nKB, int *pnWrite);
 539
 540 int lsm_flush(lsm_db *pDb);
 541
 542 /*
 543 ** Attempt to checkpoint the current database snapshot. Return an LSM
 544 ** error code if an error occurs or LSM_OK otherwise.
 545 **
 546 ** If the current snapshot has already been checkpointed, calling this
 547 ** function is a no-op. In this case if pnKB is not NULL, *pnKB is
 548 ** set to 0. Or, if the current snapshot is successfully checkpointed
 549 ** by this function and pbKB is not NULL, *pnKB is set to the number
 550 ** of bytes written to the database file since the previous checkpoint
 551 ** (the same measure as returned by the LSM_INFO_CHECKPOINT_SIZE query).
 552 */
 553 int lsm_checkpoint(lsm_db *pDb, int *pnKB);
 554
 555 /*
 556 ** CAPI: Opening and Closing Database Cursors
 557 **
 558 ** Open and close a database cursor.
 559 */
 560 int lsm_csr_open(lsm_db *pDb, lsm_cursor **ppCsr);
 561 int lsm_csr_close(lsm_cursor *pCsr);
 562
 563 /*
 564 ** CAPI: Positioning Database Cursors
 565 **
 566 ** If the fourth parameter is LSM_SEEK_EQ, LSM_SEEK_GE or LSM_SEEK_LE,
 567 ** this function searches the database for an entry with key (pKey/nKey).
 568 ** If an error occurs, an LSM error code is returned. Otherwise, LSM_OK.
 569 **
 570 ** If no error occurs and the requested key is present in the database, the
 571 ** cursor is left pointing to the entry with the specified key. Or, if the
 572 ** specified key is not present in the database the state of the cursor
 573 ** depends on the value passed as the final parameter, as follows:
 574 **
 575 ** LSM_SEEK_EQ:
 576 **   The cursor is left at EOF (invalidated). A call to lsm_csr_valid()
 577 **   returns non-zero.
 578 **
 579 ** LSM_SEEK_LE:
 580 **   The cursor is left pointing to the largest key in the database that
 581 **   is smaller than (pKey/nKey). If the database contains no keys smaller
 582 **   than (pKey/nKey), the cursor is left at EOF.
 583 **
 584 ** LSM_SEEK_GE:
 585 **   The cursor is left pointing to the smallest key in the database that
 586 **   is larger than (pKey/nKey). If the database contains no keys larger
 587 **   than (pKey/nKey), the cursor is left at EOF.
 588 **
 589 ** If the fourth parameter is LSM_SEEK_LEFAST, this function searches the
 590 ** database in a similar manner to LSM_SEEK_LE, with two differences:
 591 **
 592 ** <ol><li>Even if a key can be found (the cursor is not left at EOF), the
 593 ** lsm_csr_value() function may not be used (attempts to do so return
 594 ** LSM_MISUSE).
 595 **
 596 ** <li>The key that the cursor is left pointing to may be one that has
 597 ** been recently deleted from the database. In this case it is
 598 ** guaranteed that the returned key is larger than any key currently
 599 ** in the database that is less than or equal to (pKey/nKey).
 600 ** </ol>
 601 **
 602 ** LSM_SEEK_LEFAST requests are intended to be used to allocate database
 603 ** keys.
 604 */
 605 int lsm_csr_seek(lsm_cursor *pCsr, const void *pKey, int nKey, int eSeek);
 606
 607 int lsm_csr_first(lsm_cursor *pCsr);
 608 int lsm_csr_last(lsm_cursor *pCsr);
 609
 610 /*
 611 ** Advance the specified cursor to the next or previous key in the database.
 612 ** Return LSM_OK if successful, or an LSM error code otherwise.
 613 **
 614 ** Functions lsm_csr_seek(), lsm_csr_first() and lsm_csr_last() are "seek"
 615 ** functions. Whether or not lsm_csr_next and lsm_csr_prev may be called
 616 ** successfully also depends on the most recent seek function called on
 617 ** the cursor. Specifically:
 618 **
 619 ** <ul>
 620 ** <li> At least one seek function must have been called on the cursor.
 621 ** <li> To call lsm_csr_next(), the most recent call to a seek function must
 622 ** have been either lsm_csr_first() or a call to lsm_csr_seek() specifying
 623 ** LSM_SEEK_GE.
 624 ** <li> To call lsm_csr_prev(), the most recent call to a seek function must
 625 ** have been either lsm_csr_last() or a call to lsm_csr_seek() specifying
 626 ** LSM_SEEK_LE.
 627 ** </ul>
 628 **
 629 ** Otherwise, if the above conditions are not met when lsm_csr_next or
 630 ** lsm_csr_prev is called, LSM_MISUSE is returned and the cursor position
 631 ** remains unchanged.
 632 */
 633 int lsm_csr_next(lsm_cursor *pCsr);
 634 int lsm_csr_prev(lsm_cursor *pCsr);
 635
 636 /*
 637 ** Values that may be passed as the fourth argument to lsm_csr_seek().
 638 */
 639 #define LSM_SEEK_LEFAST   -2
 640 #define LSM_SEEK_LE       -1
 641 #define LSM_SEEK_EQ        0
 642 #define LSM_SEEK_GE        1
 643
 644 /*
 645 ** CAPI: Extracting Data From Database Cursors
 646 **
 647 ** Retrieve data from a database cursor.
 648 */
 649 int lsm_csr_valid(lsm_cursor *pCsr);
 650 int lsm_csr_key(lsm_cursor *pCsr, const void **ppKey, int *pnKey);
 651 int lsm_csr_value(lsm_cursor *pCsr, const void **ppVal, int *pnVal);
 652
 653 /*
 654 ** If no error occurs, this function compares the database key passed via
 655 ** the pKey/nKey arguments with the key that the cursor passed as the first
 656 ** argument currently points to. If the cursors key is less than, equal to
 657 ** or greater than pKey/nKey, *piRes is set to less than, equal to or greater
 658 ** than zero before returning. LSM_OK is returned in this case.
 659 **
 660 ** Or, if an error occurs, an LSM error code is returned and the final
 661 ** value of *piRes is undefined. If the cursor does not point to a valid
 662 ** key when this function is called, LSM_MISUSE is returned.
 663 */
 664 int lsm_csr_cmp(lsm_cursor *pCsr, const void *pKey, int nKey, int *piRes);
 665
 666 /*
 667 ** CAPI: Change these!!
 668 **
 669 ** Configure a callback to which debugging and other messages should
 670 ** be directed. Only useful for debugging lsm.
 671 */
 672 void lsm_config_log(lsm_db *, void (*)(void *, int, const char *), void *);
 673
 674 /*
 675 ** Configure a callback that is invoked if the database connection ever
 676 ** writes to the database file.
 677 */
 678 void lsm_config_work_hook(lsm_db *, void (*)(lsm_db *, void *), void *);
 679
 680 /* ENDOFAPI */
 681 #ifdef __cplusplus
 682 }  /* End of the 'extern "C"' block */
 683 #endif
 684 #endif /* ifndef _LSM_H */