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 _WAL_H_ 18 #define _WAL_H_ 19 20 #include "sqliteInt.h" 21 22 /* Additional values that can be added to the sync_flags argument of 23 ** sqlite3WalFrames(): 24 */ 25 #define WAL_SYNC_TRANSACTIONS 0x20 /* Sync at the end of each transaction */ 26 #define SQLITE_SYNC_MASK 0x13 /* Mask off the SQLITE_SYNC_* values */ 27 28 #ifdef SQLITE_OMIT_WAL 29 # define sqlite3WalOpen(x,y,z) 0 30 # define sqlite3WalLimit(x,y) 31 # define sqlite3WalClose(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(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 #else 48 49 #define WAL_SAVEPOINT_NDATA 4 50 51 /* Connection to a write-ahead log (WAL) file. 52 ** There is one object of this type for each pager. 53 */ 54 typedef struct Wal Wal; 55 56 /* Open and close a connection to a write-ahead log. */ 57 int sqlite3WalOpen(sqlite3_vfs*, sqlite3_file*, const char *, int, i64, Wal**); 58 int sqlite3WalClose(Wal *pWal, int sync_flags, int, u8 *); 59 60 /* Set the limiting size of a WAL file. */ 61 void sqlite3WalLimit(Wal*, i64); 62 63 /* Used by readers to open (lock) and close (unlock) a snapshot. A 64 ** snapshot is like a read-transaction. It is the state of the database 65 ** at an instant in time. sqlite3WalOpenSnapshot gets a read lock and 66 ** preserves the current state even if the other threads or processes 67 ** write to or checkpoint the WAL. sqlite3WalCloseSnapshot() closes the 68 ** transaction and releases the lock. 69 */ 70 int sqlite3WalBeginReadTransaction(Wal *pWal, int *); 71 void sqlite3WalEndReadTransaction(Wal *pWal); 72 73 /* Read a page from the write-ahead log, if it is present. */ 74 int sqlite3WalFindFrame(Wal *, Pgno, u32 *); 75 int sqlite3WalReadFrame(Wal *, u32, int, u8 *); 76 77 /* If the WAL is not empty, return the size of the database. */ 78 Pgno sqlite3WalDbsize(Wal *pWal); 79 80 /* Obtain or release the WRITER lock. */ 81 int sqlite3WalBeginWriteTransaction(Wal *pWal); 82 int sqlite3WalEndWriteTransaction(Wal *pWal); 83 84 /* Undo any frames written (but not committed) to the log */ 85 int sqlite3WalUndo(Wal *pWal, int (*xUndo)(void *, Pgno), void *pUndoCtx); 86 87 /* Return an integer that records the current (uncommitted) write 88 ** position in the WAL */ 89 void sqlite3WalSavepoint(Wal *pWal, u32 *aWalData); 90 91 /* Move the write position of the WAL back to iFrame. Called in 92 ** response to a ROLLBACK TO command. */ 93 int sqlite3WalSavepointUndo(Wal *pWal, u32 *aWalData); 94 95 /* Write a frame or frames to the log. */ 96 int sqlite3WalFrames(Wal *pWal, int, PgHdr *, Pgno, int, int); 97 98 /* Copy pages from the log to the database file */ 99 int sqlite3WalCheckpoint( 100 Wal *pWal, /* Write-ahead log connection */ 101 int eMode, /* One of PASSIVE, FULL and RESTART */ 102 int (*xBusy)(void*), /* Function to call when busy */ 103 void *pBusyArg, /* Context argument for xBusyHandler */ 104 int sync_flags, /* Flags to sync db file with (or 0) */ 105 int nBuf, /* Size of buffer nBuf */ 106 u8 *zBuf, /* Temporary buffer to use */ 107 int *pnLog, /* OUT: Number of frames in WAL */ 108 int *pnCkpt /* OUT: Number of backfilled frames in WAL */ 109 ); 110 111 /* Return the value to pass to a sqlite3_wal_hook callback, the 112 ** number of frames in the WAL at the point of the last commit since 113 ** sqlite3WalCallback() was called. If no commits have occurred since 114 ** the last call, then return 0. 115 */ 116 int sqlite3WalCallback(Wal *pWal); 117 118 /* Tell the wal layer that an EXCLUSIVE lock has been obtained (or released) 119 ** by the pager layer on the database file. 120 */ 121 int sqlite3WalExclusiveMode(Wal *pWal, int op); 122 123 /* Return true if the argument is non-NULL and the WAL module is using 124 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the 125 ** WAL module is using shared-memory, return false. 126 */ 127 int sqlite3WalHeapMemory(Wal *pWal); 128 129 int sqlite3WalCheckSalt(Wal *pWal, sqlite3_file*); 130 131 int sqlite3WalCheckpointStart(sqlite3 *, 132 Wal *pWal, /* Wal connection */ 133 u8 *aState, int nState, /* Checkpoint state to restore */ 134 int (*xBusy)(void*), /* Function to call when busy */ 135 void *pBusyArg, /* Context argument for xBusyHandler */ 136 int sync_flags, /* Flags to sync db file with (or 0) */ 137 sqlite3_ckpt **ppCkpt /* OUT: Incremental checkpoint object */ 138 ); 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 #endif /* ifndef SQLITE_OMIT_WAL */ 148 #endif /* _WAL_H_ */ 149