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*/
55typedef struct Wal Wal;
56
57/* Open and close a connection to a write-ahead log. */
58int sqlite3WalOpen(sqlite3_vfs*, sqlite3_file*, const char *, int, i64, Wal**);
59int sqlite3WalClose(Wal *pWal, sqlite3*, int sync_flags, int, u8 *);
60
61/* Set the limiting size of a WAL file. */
62void 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*/
71int sqlite3WalBeginReadTransaction(Wal *pWal, int *);
72void sqlite3WalEndReadTransaction(Wal *pWal);
73
74/* Read a page from the write-ahead log, if it is present. */
75int sqlite3WalFindFrame(Wal *, Pgno, u32 *);
76int sqlite3WalReadFrame(Wal *, u32, int, u8 *);
77
78/* If the WAL is not empty, return the size of the database. */
79Pgno sqlite3WalDbsize(Wal *pWal);
80
81/* Obtain or release the WRITER lock. */
82int sqlite3WalBeginWriteTransaction(Wal *pWal);
83int sqlite3WalEndWriteTransaction(Wal *pWal);
84
85/* Undo any frames written (but not committed) to the log */
86int 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 */
90void 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. */
94int sqlite3WalSavepointUndo(Wal *pWal, u32 *aWalData);
95
96/* Write a frame or frames to the log. */
97int sqlite3WalFrames(Wal *pWal, int, PgHdr *, Pgno, int, int);
98
99/* Copy pages from the log to the database file */
100int 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*/
118int 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*/
123int 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*/
129int sqlite3WalHeapMemory(Wal *pWal);
130
131#ifdef SQLITE_ENABLE_SNAPSHOT
132int sqlite3WalSnapshotGet(Wal *pWal, sqlite3_snapshot **ppSnapshot);
133void sqlite3WalSnapshotOpen(Wal *pWal, sqlite3_snapshot *pSnapshot);
134int sqlite3WalSnapshotRecover(Wal *pWal);
135int sqlite3WalSnapshotCheck(Wal *pWal, sqlite3_snapshot *pSnapshot);
136void 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*/
143int sqlite3WalFramesize(Wal *pWal);
144#endif
145
146/* Return the sqlite3_file object for the WAL file */
147sqlite3_file *sqlite3WalFile(Wal *pWal);
148
149#ifdef SQLITE_ENABLE_SETLK_TIMEOUT
150int sqlite3WalWriteLock(Wal *pWal, int bLock);
151void sqlite3WalDb(Wal *pWal, sqlite3 *db);
152#endif
153
154#endif /* ifndef SQLITE_OMIT_WAL */
155#endif /* SQLITE_WAL_H */
156