modernc.org/cc@v1.0.1/v2/testdata/_sqlite/ext/lsm1/lsm-test/lsmtest_tdb.h (about)

     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