ext/lsm1/lsm-test/lsmtest_tdb.h

   1
   2 /*
   3 ** This file is the interface to a very simple database library used for
   4 ** testing. The interface is similar to that of the LSM. The main virtue
   5 ** of this library is that the same API may be used to access a key-value
   6 ** store implemented by LSM, SQLite or another database system. Which
   7 ** makes it easy to use for correctness and performance tests.
   8 */
   9
  10 #ifndef __WRAPPER_H_
  11 #define __WRAPPER_H_
  12
  13 #ifdef __cplusplus
  14 extern "C" {
  15 #endif
  16
  17 #include "lsm.h"
  18
  19 typedef struct TestDb TestDb;
  20
  21 /*
  22 ** Open a new database connection. The first argument is the name of the
  23 ** database library to use. e.g. something like:
  24 **
  25 **     "sqlite3"
  26 **     "lsm"
  27 **
  28 ** See function tdb_system_name() for a list of available database systems.
  29 **
  30 ** The second argument is the name of the database to open (e.g. a filename).
  31 **
  32 ** If the third parameter is non-zero, then any existing database by the
  33 ** name of zDb is removed before opening a new one. If it is zero, then an
  34 ** existing database may be opened.
  35 */
  36 int tdb_open(const char *zLibrary, const char *zDb, int bClear, TestDb **ppDb);
  37
  38 /*
  39 ** Close a database handle.
  40 */
  41 int tdb_close(TestDb *pDb);
  42
  43 /*
  44 ** Write a new key/value into the database.
  45 */
  46 int tdb_write(TestDb *pDb, void *pKey, int nKey, void *pVal, int nVal);
  47
  48 /*
  49 ** Delete a key from the database.
  50 */
  51 int tdb_delete(TestDb *pDb, void *pKey, int nKey);
  52
  53 /*
  54 ** Delete a range of keys from the database.
  55 */
  56 int tdb_delete_range(TestDb *, void *pKey1, int nKey1, void *pKey2, int nKey2);
  57
  58 /*
  59 ** Query the database for key (pKey/nKey). If no entry is found, set *ppVal
  60 ** to 0 and *pnVal to -1 before returning. Otherwise, set *ppVal and *pnVal
  61 ** to a pointer to and size of the value associated with (pKey/nKey).
  62 */
  63 int tdb_fetch(TestDb *pDb, void *pKey, int nKey, void **ppVal, int *pnVal);
  64
  65 /*
  66 ** Open and close nested transactions. Currently, these functions only
  67 ** work for SQLite3 and LSM systems. Use the tdb_transaction_support()
  68 ** function to determine if a given TestDb handle supports these methods.
  69 **
  70 ** These functions and the iLevel parameter follow the same conventions as
  71 ** the SQLite 4 transaction interface. Note that this is slightly different
  72 ** from the way LSM does things. As follows:
  73 **
  74 ** tdb_begin():
  75 **   A successful call to tdb_begin() with (iLevel>1) guarantees that
  76 **   there are at least (iLevel-1) write transactions open. If iLevel==1,
  77 **   then it guarantees that at least a read-transaction is open. Calling
  78 **   tdb_begin() with iLevel==0 is a no-op.
  79 **
  80 ** tdb_commit():
  81 **   A successful call to tdb_commit() with (iLevel>1) guarantees that
  82 **   there are at most (iLevel-1) write transactions open. If iLevel==1,
  83 **   then it guarantees that there are no write transactions open (although
  84 **   a read-transaction may remain open).  Calling tdb_commit() with
  85 **   iLevel==0 ensures that all transactions, read or write, have been
  86 **   closed and committed.
  87 **
  88 ** tdb_rollback():
  89 **   This call is similar to tdb_commit(), except that instead of committing
  90 **   transactions, it reverts them. For example, calling tdb_rollback() with
  91 **   iLevel==2 ensures that there is at most one write transaction open, and
  92 **   restores the database to the state that it was in when that transaction
  93 **   was opened.
  94 **
  95 **   In other words, tdb_commit() just closes transactions - tdb_rollback()
  96 **   closes transactions and then restores the database to the state it
  97 **   was in before those transactions were even opened.
  98 */
  99 int tdb_begin(TestDb *pDb, int iLevel);
 100 int tdb_commit(TestDb *pDb, int iLevel);
 101 int tdb_rollback(TestDb *pDb, int iLevel);
 102
 103 /*
 104 ** Return true if transactions are supported, or false otherwise.
 105 */
 106 int tdb_transaction_support(TestDb *pDb);
 107
 108 /*
 109 ** Return the name of the database library (as passed to tdb_open()) used
 110 ** by the handled passed as the first argument.
 111 */
 112 const char *tdb_library_name(TestDb *pDb);
 113
 114 /*
 115 ** Scan a range of database keys. Invoke the callback function for each
 116 ** key visited.
 117 */
 118 int tdb_scan(
 119   TestDb *pDb,                    /* Database handle */
 120   void *pCtx,                     /* Context pointer to pass to xCallback */
 121   int bReverse,                   /* True to scan in reverse order */
 122   void *pKey1, int nKey1,         /* Start of search */
 123   void *pKey2, int nKey2,         /* End of search */
 124   void (*xCallback)(void *pCtx, void *pKey, int nKey, void *pVal, int nVal)
 125 );
 126
 127 const char *tdb_system_name(int i);
 128 const char *tdb_default_db(const char *zSys);
 129
 130 int tdb_lsm_open(const char *zCfg, const char *zDb, int bClear, TestDb **ppDb);
 131
 132 /*
 133 ** If the TestDb handle passed as an argument is a wrapper around an LSM
 134 ** database, return the LSM handle. Otherwise, if the argument is some other
 135 ** database system, return NULL.
 136 */
 137 lsm_db *tdb_lsm(TestDb *pDb);
 138
 139 /*
 140 ** Return true if the db passed as an argument is a multi-threaded LSM
 141 ** connection.
 142 */
 143 int tdb_lsm_multithread(TestDb *pDb);
 144
 145 /*
 146 ** Return a pointer to the lsm_env object used by all lsm database
 147 ** connections initialized as a copy of the object returned by
 148 ** lsm_default_env(). It may be modified (e.g. to override functions)
 149 ** if the caller can guarantee that it is not already in use.
 150 */
 151 lsm_env *tdb_lsm_env(void);
 152
 153 /*
 154 ** The following functions only work with LSM database handles. It is
 155 ** illegal to call them with any other type of database handle specified
 156 ** as an argument.
 157 */
 158 void tdb_lsm_enable_log(TestDb *pDb, int bEnable);
 159 void tdb_lsm_application_crash(TestDb *pDb);
 160 void tdb_lsm_prepare_system_crash(TestDb *pDb);
 161 void tdb_lsm_system_crash(TestDb *pDb);
 162 void tdb_lsm_prepare_sync_crash(TestDb *pDb, int iSync);
 163
 164
 165 void tdb_lsm_safety(TestDb *pDb, int eMode);
 166 void tdb_lsm_config_work_hook(TestDb *pDb, void (*)(lsm_db *, void *), void *);
 167 void tdb_lsm_write_hook(TestDb *, void(*)(void*,int,lsm_i64,int,int), void*);
 168 int tdb_lsm_config_str(TestDb *pDb, const char *zStr);
 169
 170 #ifdef __cplusplus
 171 }  /* End of the 'extern "C"' block */
 172 #endif
 173
 174 #endif