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