src/wal.h

   1 /*
   2 ** 2010 February 1
   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 ** This header file defines the interface to the write-ahead logging
  13 ** system. Refer to the comments below and the header comment attached to
  14 ** the implementation of each function in log.c for further details.
  15 */
  16
  17 #ifndef SQLITE_WAL_H
  18 #define SQLITE_WAL_H
  19
  20 #include "sqliteInt.h"
  21
  22 /* Macros for extracting appropriate sync flags for either transaction
  23 ** commits (WAL_SYNC_FLAGS(X)) or for checkpoint ops (CKPT_SYNC_FLAGS(X)):
  24 */
  25 #define WAL_SYNC_FLAGS(X)   ((X)&0x03)
  26 #define CKPT_SYNC_FLAGS(X)  (((X)>>2)&0x03)
  27
  28 #ifdef SQLITE_OMIT_WAL
  29 # define sqlite3WalOpen(x,y,z)                   0
  30 # define sqlite3WalLimit(x,y)
  31 # define sqlite3WalClose(v,w,x,y,z)              0
  32 # define sqlite3WalBeginReadTransaction(y,z)     0
  33 # define sqlite3WalEndReadTransaction(z)
  34 # define sqlite3WalDbsize(y)                     0
  35 # define sqlite3WalBeginWriteTransaction(y)      0
  36 # define sqlite3WalEndWriteTransaction(x)        0
  37 # define sqlite3WalUndo(x,y,z)                   0
  38 # define sqlite3WalSavepoint(y,z)
  39 # define sqlite3WalSavepointUndo(y,z)            0
  40 # define sqlite3WalFrames(u,v,w,x,y,z)           0
  41 # define sqlite3WalCheckpoint(q,r,s,t,u,v,w,x,y,z) 0
  42 # define sqlite3WalCallback(z)                   0
  43 # define sqlite3WalExclusiveMode(y,z)            0
  44 # define sqlite3WalHeapMemory(z)                 0
  45 # define sqlite3WalFramesize(z)                  0
  46 # define sqlite3WalFindFrame(x,y,z)              0
  47 # define sqlite3WalFile(x)                       0
  48 # undef SQLITE_USE_SEH
  49 #else
  50
  51 #define WAL_SAVEPOINT_NDATA 4
  52
  53 /* Connection to a write-ahead log (WAL) file.
  54 ** There is one object of this type for each pager.
  55 */
  56 typedef struct Wal Wal;
  57
  58 /* Open and close a connection to a write-ahead log. */
  59 int sqlite3WalOpen(sqlite3_vfs*, sqlite3_file*, const char *, int, i64, Wal**);
  60 int sqlite3WalClose(Wal *pWal, sqlite3*, int sync_flags, int, u8 *);
  61
  62 /* Set the limiting size of a WAL file. */
  63 void sqlite3WalLimit(Wal*, i64);
  64
  65 /* Used by readers to open (lock) and close (unlock) a snapshot.  A
  66 ** snapshot is like a read-transaction.  It is the state of the database
  67 ** at an instant in time.  sqlite3WalOpenSnapshot gets a read lock and
  68 ** preserves the current state even if the other threads or processes
  69 ** write to or checkpoint the WAL.  sqlite3WalCloseSnapshot() closes the
  70 ** transaction and releases the lock.
  71 */
  72 int sqlite3WalBeginReadTransaction(Wal *pWal, int *);
  73 void sqlite3WalEndReadTransaction(Wal *pWal);
  74
  75 /* Read a page from the write-ahead log, if it is present. */
  76 int sqlite3WalFindFrame(Wal *, Pgno, u32 *);
  77 int sqlite3WalReadFrame(Wal *, u32, int, u8 *);
  78
  79 /* If the WAL is not empty, return the size of the database. */
  80 Pgno sqlite3WalDbsize(Wal *pWal);
  81
  82 /* Obtain or release the WRITER lock. */
  83 int sqlite3WalBeginWriteTransaction(Wal *pWal);
  84 int sqlite3WalEndWriteTransaction(Wal *pWal);
  85
  86 /* Undo any frames written (but not committed) to the log */
  87 int sqlite3WalUndo(Wal *pWal, int (*xUndo)(void *, Pgno), void *pUndoCtx);
  88
  89 /* Return an integer that records the current (uncommitted) write
  90 ** position in the WAL */
  91 void sqlite3WalSavepoint(Wal *pWal, u32 *aWalData);
  92
  93 /* Move the write position of the WAL back to iFrame.  Called in
  94 ** response to a ROLLBACK TO command. */
  95 int sqlite3WalSavepointUndo(Wal *pWal, u32 *aWalData);
  96
  97 /* Write a frame or frames to the log. */
  98 int sqlite3WalFrames(Wal *pWal, int, PgHdr *, Pgno, int, int);
  99
 100 /* Copy pages from the log to the database file */
 101 int sqlite3WalCheckpoint(
 102   Wal *pWal,                      /* Write-ahead log connection */
 103   sqlite3 *db,                    /* Check this handle's interrupt flag */
 104   int eMode,                      /* One of PASSIVE, FULL and RESTART */
 105   int (*xBusy)(void*),            /* Function to call when busy */
 106   void *pBusyArg,                 /* Context argument for xBusyHandler */
 107   int sync_flags,                 /* Flags to sync db file with (or 0) */
 108   int nBuf,                       /* Size of buffer nBuf */
 109   u8 *zBuf,                       /* Temporary buffer to use */
 110   int *pnLog,                     /* OUT: Number of frames in WAL */
 111   int *pnCkpt                     /* OUT: Number of backfilled frames in WAL */
 112 );
 113
 114 /* Return the value to pass to a sqlite3_wal_hook callback, the
 115 ** number of frames in the WAL at the point of the last commit since
 116 ** sqlite3WalCallback() was called.  If no commits have occurred since
 117 ** the last call, then return 0.
 118 */
 119 int sqlite3WalCallback(Wal *pWal);
 120
 121 /* Tell the wal layer that an EXCLUSIVE lock has been obtained (or released)
 122 ** by the pager layer on the database file.
 123 */
 124 int sqlite3WalExclusiveMode(Wal *pWal, int op);
 125
 126 /* Return true if the argument is non-NULL and the WAL module is using
 127 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
 128 ** WAL module is using shared-memory, return false.
 129 */
 130 int sqlite3WalHeapMemory(Wal *pWal);
 131
 132 #ifdef SQLITE_ENABLE_SNAPSHOT
 133 int sqlite3WalSnapshotGet(Wal *pWal, sqlite3_snapshot **ppSnapshot);
 134 void sqlite3WalSnapshotOpen(Wal *pWal, sqlite3_snapshot *pSnapshot);
 135 int sqlite3WalSnapshotRecover(Wal *pWal);
 136 int sqlite3WalSnapshotCheck(Wal *pWal, sqlite3_snapshot *pSnapshot);
 137 void sqlite3WalSnapshotUnlock(Wal *pWal);
 138 #endif
 139
 140 #ifdef SQLITE_ENABLE_ZIPVFS
 141 /* If the WAL file is not empty, return the number of bytes of content
 142 ** stored in each frame (i.e. the db page-size when the WAL was created).
 143 */
 144 int sqlite3WalFramesize(Wal *pWal);
 145 #endif
 146
 147 /* Return the sqlite3_file object for the WAL file */
 148 sqlite3_file *sqlite3WalFile(Wal *pWal);
 149
 150 #ifdef SQLITE_ENABLE_SETLK_TIMEOUT
 151 int sqlite3WalWriteLock(Wal *pWal, int bLock);
 152 void sqlite3WalDb(Wal *pWal, sqlite3 *db);
 153 #endif
 154
 155 #ifdef SQLITE_USE_SEH
 156 int sqlite3WalSystemErrno(Wal*);
 157 #endif
 158
 159 #endif /* ifndef SQLITE_OMIT_WAL */
 160 #endif /* SQLITE_WAL_H */