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 */ 685