4 ** The author disclaims copyright to this source code. In place of
5 ** a legal notice, here is a blessing:
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.
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.
20 #include "sqliteInt.h"
22 /* Additional values that can be added to the sync_flags argument of
23 ** sqlite3WalFrames():
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 */
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 # define sqlite3WalFile(x) 0
50 #define WAL_SAVEPOINT_NDATA 4
52 /* Connection to a write-ahead log (WAL) file.
53 ** There is one object of this type for each pager.
55 typedef struct Wal Wal
;
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
, int sync_flags
, int, u8
*);
61 /* Set the limiting size of a WAL file. */
62 void sqlite3WalLimit(Wal
*, i64
);
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.
71 int sqlite3WalBeginReadTransaction(Wal
*pWal
, int *);
72 void sqlite3WalEndReadTransaction(Wal
*pWal
);
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
*);
78 /* If the WAL is not empty, return the size of the database. */
79 Pgno
sqlite3WalDbsize(Wal
*pWal
);
81 /* Obtain or release the WRITER lock. */
82 int sqlite3WalBeginWriteTransaction(Wal
*pWal
);
83 int sqlite3WalEndWriteTransaction(Wal
*pWal
);
85 /* Undo any frames written (but not committed) to the log */
86 int sqlite3WalUndo(Wal
*pWal
, int (*xUndo
)(void *, Pgno
), void *pUndoCtx
);
88 /* Return an integer that records the current (uncommitted) write
89 ** position in the WAL */
90 void sqlite3WalSavepoint(Wal
*pWal
, u32
*aWalData
);
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
);
96 /* Write a frame or frames to the log. */
97 int sqlite3WalFrames(Wal
*pWal
, int, PgHdr
*, Pgno
, int, int);
99 /* Copy pages from the log to the database file */
100 int sqlite3WalCheckpoint(
101 Wal
*pWal
, /* Write-ahead log connection */
102 int eMode
, /* One of PASSIVE, FULL and RESTART */
103 int (*xBusy
)(void*), /* Function to call when busy */
104 void *pBusyArg
, /* Context argument for xBusyHandler */
105 int sync_flags
, /* Flags to sync db file with (or 0) */
106 int nBuf
, /* Size of buffer nBuf */
107 u8
*zBuf
, /* Temporary buffer to use */
108 int *pnLog
, /* OUT: Number of frames in WAL */
109 int *pnCkpt
/* OUT: Number of backfilled frames in WAL */
112 /* Return the value to pass to a sqlite3_wal_hook callback, the
113 ** number of frames in the WAL at the point of the last commit since
114 ** sqlite3WalCallback() was called. If no commits have occurred since
115 ** the last call, then return 0.
117 int sqlite3WalCallback(Wal
*pWal
);
119 /* Tell the wal layer that an EXCLUSIVE lock has been obtained (or released)
120 ** by the pager layer on the database file.
122 int sqlite3WalExclusiveMode(Wal
*pWal
, int op
);
124 /* Return true if the argument is non-NULL and the WAL module is using
125 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
126 ** WAL module is using shared-memory, return false.
128 int sqlite3WalHeapMemory(Wal
*pWal
);
130 #ifdef SQLITE_ENABLE_SNAPSHOT
131 int sqlite3WalSnapshotGet(Wal
*pWal
, sqlite3_snapshot
**ppSnapshot
);
132 void sqlite3WalSnapshotOpen(Wal
*pWal
, sqlite3_snapshot
*pSnapshot
);
135 #ifdef SQLITE_ENABLE_ZIPVFS
136 /* If the WAL file is not empty, return the number of bytes of content
137 ** stored in each frame (i.e. the db page-size when the WAL was created).
139 int sqlite3WalFramesize(Wal
*pWal
);
142 /* Return the sqlite3_file object for the WAL file */
143 sqlite3_file
*sqlite3WalFile(Wal
*pWal
);
145 #endif /* ifndef SQLITE_OMIT_WAL */
146 #endif /* SQLITE_WAL_H */