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 *************************************************************************
13 ** This file contains the implementation of a write-ahead log (WAL) used in
14 ** "journal_mode=WAL" mode.
16 ** WRITE-AHEAD LOG (WAL) FILE FORMAT
18 ** A WAL file consists of a header followed by zero or more "frames".
19 ** Each frame records the revised content of a single page from the
20 ** database file. All changes to the database are recorded by writing
21 ** frames into the WAL. Transactions commit when a frame is written that
22 ** contains a commit marker. A single WAL can and usually does record
23 ** multiple transactions. Periodically, the content of the WAL is
24 ** transferred back into the database file in an operation called a
27 ** A single WAL file can be used multiple times. In other words, the
28 ** WAL can fill up with frames and then be checkpointed and then new
29 ** frames can overwrite the old ones. A WAL always grows from beginning
30 ** toward the end. Checksums and counters attached to each frame are
31 ** used to determine which frames within the WAL are valid and which
32 ** are leftovers from prior checkpoints.
34 ** The WAL header is 32 bytes in size and consists of the following eight
35 ** big-endian 32-bit unsigned integer values:
37 ** 0: Magic number. 0x377f0682 or 0x377f0683
38 ** 4: File format version. Currently 3007000
39 ** 8: Database page size. Example: 1024
40 ** 12: Checkpoint sequence number
41 ** 16: Salt-1, random integer incremented with each checkpoint
42 ** 20: Salt-2, a different random integer changing with each ckpt
43 ** 24: Checksum-1 (first part of checksum for first 24 bytes of header).
44 ** 28: Checksum-2 (second part of checksum for first 24 bytes of header).
46 ** Immediately following the wal-header are zero or more frames. Each
47 ** frame consists of a 24-byte frame-header followed by a <page-size> bytes
48 ** of page data. The frame-header is six big-endian 32-bit unsigned
49 ** integer values, as follows:
52 ** 4: For commit records, the size of the database image in pages
53 ** after the commit. For all other records, zero.
54 ** 8: Salt-1 (copied from the header)
55 ** 12: Salt-2 (copied from the header)
59 ** A frame is considered valid if and only if the following conditions are
62 ** (1) The salt-1 and salt-2 values in the frame-header match
63 ** salt values in the wal-header
65 ** (2) The checksum values in the final 8 bytes of the frame-header
66 ** exactly match the checksum computed consecutively on the
67 ** WAL header and the first 8 bytes and the content of all frames
68 ** up to and including the current frame.
70 ** The checksum is computed using 32-bit big-endian integers if the
71 ** magic number in the first 4 bytes of the WAL is 0x377f0683 and it
72 ** is computed using little-endian if the magic number is 0x377f0682.
73 ** The checksum values are always stored in the frame header in a
74 ** big-endian format regardless of which byte order is used to compute
75 ** the checksum. The checksum is computed by interpreting the input as
76 ** an even number of unsigned 32-bit integers: x[0] through x[N]. The
77 ** algorithm used for the checksum is as follows:
79 ** for i from 0 to n-1 step 2:
84 ** Note that s0 and s1 are both weighted checksums using fibonacci weights
85 ** in reverse order (the largest fibonacci weight occurs on the first element
86 ** of the sequence being summed.) The s1 value spans all 32-bit
87 ** terms of the sequence whereas s0 omits the final term.
89 ** On a checkpoint, the WAL is first VFS.xSync-ed, then valid content of the
90 ** WAL is transferred into the database, then the database is VFS.xSync-ed.
91 ** The VFS.xSync operations serve as write barriers - all writes launched
92 ** before the xSync must complete before any write that launches after the
95 ** After each checkpoint, the salt-1 value is incremented and the salt-2
96 ** value is randomized. This prevents old and new frames in the WAL from
97 ** being considered valid at the same time and being checkpointing together
102 ** To read a page from the database (call it page number P), a reader
103 ** first checks the WAL to see if it contains page P. If so, then the
104 ** last valid instance of page P that is a followed by a commit frame
105 ** or is a commit frame itself becomes the value read. If the WAL
106 ** contains no copies of page P that are valid and which are a commit
107 ** frame or are followed by a commit frame, then page P is read from
108 ** the database file.
110 ** To start a read transaction, the reader records the index of the last
111 ** valid frame in the WAL. The reader uses this recorded "mxFrame" value
112 ** for all subsequent read operations. New transactions can be appended
113 ** to the WAL, but as long as the reader uses its original mxFrame value
114 ** and ignores the newly appended content, it will see a consistent snapshot
115 ** of the database from a single point in time. This technique allows
116 ** multiple concurrent readers to view different versions of the database
117 ** content simultaneously.
119 ** The reader algorithm in the previous paragraphs works correctly, but
120 ** because frames for page P can appear anywhere within the WAL, the
121 ** reader has to scan the entire WAL looking for page P frames. If the
122 ** WAL is large (multiple megabytes is typical) that scan can be slow,
123 ** and read performance suffers. To overcome this problem, a separate
124 ** data structure called the wal-index is maintained to expedite the
125 ** search for frames of a particular page.
129 ** Conceptually, the wal-index is shared memory, though VFS implementations
130 ** might choose to implement the wal-index using a mmapped file. Because
131 ** the wal-index is shared memory, SQLite does not support journal_mode=WAL
132 ** on a network filesystem. All users of the database must be able to
135 ** The wal-index is transient. After a crash, the wal-index can (and should
136 ** be) reconstructed from the original WAL file. In fact, the VFS is required
137 ** to either truncate or zero the header of the wal-index when the last
138 ** connection to it closes. Because the wal-index is transient, it can
139 ** use an architecture-specific format; it does not have to be cross-platform.
140 ** Hence, unlike the database and WAL file formats which store all values
141 ** as big endian, the wal-index can store multi-byte values in the native
142 ** byte order of the host computer.
144 ** The purpose of the wal-index is to answer this question quickly: Given
145 ** a page number P, return the index of the last frame for page P in the WAL,
146 ** or return NULL if there are no frames for page P in the WAL.
148 ** The wal-index consists of a header region, followed by an one or
149 ** more index blocks.
151 ** The wal-index header contains the total number of frames within the WAL
152 ** in the the mxFrame field.
154 ** Each index block except for the first contains information on
155 ** HASHTABLE_NPAGE frames. The first index block contains information on
156 ** HASHTABLE_NPAGE_ONE frames. The values of HASHTABLE_NPAGE_ONE and
157 ** HASHTABLE_NPAGE are selected so that together the wal-index header and
158 ** first index block are the same size as all other index blocks in the
161 ** Each index block contains two sections, a page-mapping that contains the
162 ** database page number associated with each wal frame, and a hash-table
163 ** that allows readers to query an index block for a specific page number.
164 ** The page-mapping is an array of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE
165 ** for the first index block) 32-bit page numbers. The first entry in the
166 ** first index-block contains the database page number corresponding to the
167 ** first frame in the WAL file. The first entry in the second index block
168 ** in the WAL file corresponds to the (HASHTABLE_NPAGE_ONE+1)th frame in
169 ** the log, and so on.
171 ** The last index block in a wal-index usually contains less than the full
172 ** complement of HASHTABLE_NPAGE (or HASHTABLE_NPAGE_ONE) page-numbers,
173 ** depending on the contents of the WAL file. This does not change the
174 ** allocated size of the page-mapping array - the page-mapping array merely
175 ** contains unused entries.
177 ** Even without using the hash table, the last frame for page P
178 ** can be found by scanning the page-mapping sections of each index block
179 ** starting with the last index block and moving toward the first, and
180 ** within each index block, starting at the end and moving toward the
181 ** beginning. The first entry that equals P corresponds to the frame
182 ** holding the content for that page.
184 ** The hash table consists of HASHTABLE_NSLOT 16-bit unsigned integers.
185 ** HASHTABLE_NSLOT = 2*HASHTABLE_NPAGE, and there is one entry in the
186 ** hash table for each page number in the mapping section, so the hash
187 ** table is never more than half full. The expected number of collisions
188 ** prior to finding a match is 1. Each entry of the hash table is an
189 ** 1-based index of an entry in the mapping section of the same
190 ** index block. Let K be the 1-based index of the largest entry in
191 ** the mapping section. (For index blocks other than the last, K will
192 ** always be exactly HASHTABLE_NPAGE (4096) and for the last index block
193 ** K will be (mxFrame%HASHTABLE_NPAGE).) Unused slots of the hash table
194 ** contain a value of 0.
196 ** To look for page P in the hash table, first compute a hash iKey on
199 ** iKey = (P * 383) % HASHTABLE_NSLOT
201 ** Then start scanning entries of the hash table, starting with iKey
202 ** (wrapping around to the beginning when the end of the hash table is
203 ** reached) until an unused hash slot is found. Let the first unused slot
204 ** be at index iUnused. (iUnused might be less than iKey if there was
205 ** wrap-around.) Because the hash table is never more than half full,
206 ** the search is guaranteed to eventually hit an unused entry. Let
207 ** iMax be the value between iKey and iUnused, closest to iUnused,
208 ** where aHash[iMax]==P. If there is no iMax entry (if there exists
209 ** no hash slot such that aHash[i]==p) then page P is not in the
210 ** current index block. Otherwise the iMax-th mapping entry of the
211 ** current index block corresponds to the last entry that references
214 ** A hash search begins with the last index block and moves toward the
215 ** first index block, looking for entries corresponding to page P. On
216 ** average, only two or three slots in each index block need to be
217 ** examined in order to either find the last entry for page P, or to
218 ** establish that no such entry exists in the block. Each index block
219 ** holds over 4000 entries. So two or three index blocks are sufficient
220 ** to cover a typical 10 megabyte WAL file, assuming 1K pages. 8 or 10
221 ** comparisons (on average) suffice to either locate a frame in the
222 ** WAL or to establish that the frame does not exist in the WAL. This
223 ** is much faster than scanning the entire 10MB WAL.
225 ** Note that entries are added in order of increasing K. Hence, one
226 ** reader might be using some value K0 and a second reader that started
227 ** at a later time (after additional transactions were added to the WAL
228 ** and to the wal-index) might be using a different value K1, where K1>K0.
229 ** Both readers can use the same hash table and mapping section to get
230 ** the correct result. There may be entries in the hash table with
231 ** K>K0 but to the first reader, those entries will appear to be unused
232 ** slots in the hash table and so the first reader will get an answer as
233 ** if no values greater than K0 had ever been inserted into the hash table
234 ** in the first place - which is what reader one wants. Meanwhile, the
235 ** second reader using K1 will see additional values that were inserted
236 ** later, which is exactly what reader two wants.
238 ** When a rollback occurs, the value of K is decreased. Hash table entries
239 ** that correspond to frames greater than the new K value are removed
240 ** from the hash table at this point.
242 #ifndef SQLITE_OMIT_WAL
247 ** Trace output macros
249 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
250 int sqlite3WalTrace
= 0;
251 # define WALTRACE(X) if(sqlite3WalTrace) sqlite3DebugPrintf X
257 ** The maximum (and only) versions of the wal and wal-index formats
258 ** that may be interpreted by this version of SQLite.
260 ** If a client begins recovering a WAL file and finds that (a) the checksum
261 ** values in the wal-header are correct and (b) the version field is not
262 ** WAL_MAX_VERSION, recovery fails and SQLite returns SQLITE_CANTOPEN.
264 ** Similarly, if a client successfully reads a wal-index header (i.e. the
265 ** checksum test is successful) and finds that the version field is not
266 ** WALINDEX_MAX_VERSION, then no read-transaction is opened and SQLite
267 ** returns SQLITE_CANTOPEN.
269 #define WAL_MAX_VERSION 3007000
270 #define WALINDEX_MAX_VERSION 3007000
273 ** Indices of various locking bytes. WAL_NREADER is the number
274 ** of available reader locks and should be at least 3.
276 #define WAL_WRITE_LOCK 0
277 #define WAL_ALL_BUT_WRITE 1
278 #define WAL_CKPT_LOCK 1
279 #define WAL_RECOVER_LOCK 2
280 #define WAL_READ_LOCK(I) (3+(I))
281 #define WAL_NREADER (SQLITE_SHM_NLOCK-3)
284 /* Object declarations */
285 typedef struct WalIndexHdr WalIndexHdr
;
286 typedef struct WalIterator WalIterator
;
287 typedef struct WalCkptInfo WalCkptInfo
;
291 ** The following object holds a copy of the wal-index header content.
293 ** The actual header in the wal-index consists of two copies of this
296 ** The szPage value can be any power of 2 between 512 and 32768, inclusive.
297 ** Or it can be 1 to represent a 65536-byte page. The latter case was
298 ** added in 3.7.1 when support for 64K pages was added.
301 u32 iVersion
; /* Wal-index version */
302 u32 unused
; /* Unused (padding) field */
303 u32 iChange
; /* Counter incremented each transaction */
304 u8 isInit
; /* 1 when initialized */
305 u8 bigEndCksum
; /* True if checksums in WAL are big-endian */
306 u16 szPage
; /* Database page size in bytes. 1==64K */
307 u32 mxFrame
; /* Index of last valid frame in the WAL */
308 u32 nPage
; /* Size of database in pages */
309 u32 aFrameCksum
[2]; /* Checksum of last frame in log */
310 u32 aSalt
[2]; /* Two salt values copied from WAL header */
311 u32 aCksum
[2]; /* Checksum over all prior fields */
315 ** A copy of the following object occurs in the wal-index immediately
316 ** following the second copy of the WalIndexHdr. This object stores
317 ** information used by checkpoint.
319 ** nBackfill is the number of frames in the WAL that have been written
320 ** back into the database. (We call the act of moving content from WAL to
321 ** database "backfilling".) The nBackfill number is never greater than
322 ** WalIndexHdr.mxFrame. nBackfill can only be increased by threads
323 ** holding the WAL_CKPT_LOCK lock (which includes a recovery thread).
324 ** However, a WAL_WRITE_LOCK thread can move the value of nBackfill from
325 ** mxFrame back to zero when the WAL is reset.
327 ** There is one entry in aReadMark[] for each reader lock. If a reader
328 ** holds read-lock K, then the value in aReadMark[K] is no greater than
329 ** the mxFrame for that reader. The value READMARK_NOT_USED (0xffffffff)
330 ** for any aReadMark[] means that entry is unused. aReadMark[0] is
331 ** a special case; its value is never used and it exists as a place-holder
332 ** to avoid having to offset aReadMark[] indexs by one. Readers holding
333 ** WAL_READ_LOCK(0) always ignore the entire WAL and read all content
334 ** directly from the database.
336 ** The value of aReadMark[K] may only be changed by a thread that
337 ** is holding an exclusive lock on WAL_READ_LOCK(K). Thus, the value of
338 ** aReadMark[K] cannot changed while there is a reader is using that mark
339 ** since the reader will be holding a shared lock on WAL_READ_LOCK(K).
341 ** The checkpointer may only transfer frames from WAL to database where
342 ** the frame numbers are less than or equal to every aReadMark[] that is
343 ** in use (that is, every aReadMark[j] for which there is a corresponding
344 ** WAL_READ_LOCK(j)). New readers (usually) pick the aReadMark[] with the
345 ** largest value and will increase an unused aReadMark[] to mxFrame if there
346 ** is not already an aReadMark[] equal to mxFrame. The exception to the
347 ** previous sentence is when nBackfill equals mxFrame (meaning that everything
348 ** in the WAL has been backfilled into the database) then new readers
349 ** will choose aReadMark[0] which has value 0 and hence such reader will
350 ** get all their all content directly from the database file and ignore
353 ** Writers normally append new frames to the end of the WAL. However,
354 ** if nBackfill equals mxFrame (meaning that all WAL content has been
355 ** written back into the database) and if no readers are using the WAL
356 ** (in other words, if there are no WAL_READ_LOCK(i) where i>0) then
357 ** the writer will first "reset" the WAL back to the beginning and start
358 ** writing new content beginning at frame 1.
360 ** We assume that 32-bit loads are atomic and so no locks are needed in
361 ** order to read from any aReadMark[] entries.
364 u32 nBackfill
; /* Number of WAL frames backfilled into DB */
365 u32 aReadMark
[WAL_NREADER
]; /* Reader marks */
367 #define READMARK_NOT_USED 0xffffffff
370 /* A block of WALINDEX_LOCK_RESERVED bytes beginning at
371 ** WALINDEX_LOCK_OFFSET is reserved for locks. Since some systems
372 ** only support mandatory file-locks, we do not read or write data
373 ** from the region of the file on which locks are applied.
375 #define WALINDEX_LOCK_OFFSET (sizeof(WalIndexHdr)*2 + sizeof(WalCkptInfo))
376 #define WALINDEX_LOCK_RESERVED 16
377 #define WALINDEX_HDR_SIZE (WALINDEX_LOCK_OFFSET+WALINDEX_LOCK_RESERVED)
379 /* Size of header before each frame in wal */
380 #define WAL_FRAME_HDRSIZE 24
382 /* Size of write ahead log header, including checksum. */
383 /* #define WAL_HDRSIZE 24 */
384 #define WAL_HDRSIZE 32
386 /* WAL magic value. Either this value, or the same value with the least
387 ** significant bit also set (WAL_MAGIC | 0x00000001) is stored in 32-bit
388 ** big-endian format in the first 4 bytes of a WAL file.
390 ** If the LSB is set, then the checksums for each frame within the WAL
391 ** file are calculated by treating all data as an array of 32-bit
392 ** big-endian words. Otherwise, they are calculated by interpreting
393 ** all data as 32-bit little-endian words.
395 #define WAL_MAGIC 0x377f0682
398 ** Return the offset of frame iFrame in the write-ahead log file,
399 ** assuming a database page size of szPage bytes. The offset returned
400 ** is to the start of the write-ahead log frame-header.
402 #define walFrameOffset(iFrame, szPage) ( \
403 WAL_HDRSIZE + ((iFrame)-1)*(i64)((szPage)+WAL_FRAME_HDRSIZE) \
407 ** An open write-ahead log file is represented by an instance of the
411 sqlite3_vfs
*pVfs
; /* The VFS used to create pDbFd */
412 sqlite3_file
*pDbFd
; /* File handle for the database file */
413 sqlite3_file
*pWalFd
; /* File handle for WAL file */
414 u32 iCallback
; /* Value to pass to log callback (or 0) */
415 i64 mxWalSize
; /* Truncate WAL to this size upon reset */
416 int nWiData
; /* Size of array apWiData */
417 int szFirstBlock
; /* Size of first block written to WAL file */
418 volatile u32
**apWiData
; /* Pointer to wal-index content in memory */
419 u32 szPage
; /* Database page size */
420 i16 readLock
; /* Which read lock is being held. -1 for none */
421 u8 syncFlags
; /* Flags to use to sync header writes */
422 u8 exclusiveMode
; /* Non-zero if connection is in exclusive mode */
423 u8 writeLock
; /* True if in a write transaction */
424 u8 ckptLock
; /* True if holding a checkpoint lock */
425 u8 readOnly
; /* WAL_RDWR, WAL_RDONLY, or WAL_SHM_RDONLY */
426 u8 truncateOnCommit
; /* True to truncate WAL file on commit */
427 u8 syncHeader
; /* Fsync the WAL header if true */
428 u8 padToSectorBoundary
; /* Pad transactions out to the next sector */
429 WalIndexHdr hdr
; /* Wal-index header for current transaction */
430 const char *zWalName
; /* Name of WAL file */
431 u32 nCkpt
; /* Checkpoint sequence counter in the wal-header */
433 u8 lockError
; /* True if a locking error has occurred */
438 ** Candidate values for Wal.exclusiveMode.
440 #define WAL_NORMAL_MODE 0
441 #define WAL_EXCLUSIVE_MODE 1
442 #define WAL_HEAPMEMORY_MODE 2
445 ** Possible values for WAL.readOnly
447 #define WAL_RDWR 0 /* Normal read/write connection */
448 #define WAL_RDONLY 1 /* The WAL file is readonly */
449 #define WAL_SHM_RDONLY 2 /* The SHM file is readonly */
452 ** Each page of the wal-index mapping contains a hash-table made up of
453 ** an array of HASHTABLE_NSLOT elements of the following type.
458 ** This structure is used to implement an iterator that loops through
459 ** all frames in the WAL in database page order. Where two or more frames
460 ** correspond to the same database page, the iterator visits only the
461 ** frame most recently written to the WAL (in other words, the frame with
462 ** the largest index).
464 ** The internals of this structure are only accessed by:
466 ** walIteratorInit() - Create a new iterator,
467 ** walIteratorNext() - Step an iterator,
468 ** walIteratorFree() - Free an iterator.
470 ** This functionality is used by the checkpoint code (see walCheckpoint()).
473 int iPrior
; /* Last result returned from the iterator */
474 int nSegment
; /* Number of entries in aSegment[] */
476 int iNext
; /* Next slot in aIndex[] not yet returned */
477 ht_slot
*aIndex
; /* i0, i1, i2... such that aPgno[iN] ascend */
478 u32
*aPgno
; /* Array of page numbers. */
479 int nEntry
; /* Nr. of entries in aPgno[] and aIndex[] */
480 int iZero
; /* Frame number associated with aPgno[0] */
481 } aSegment
[1]; /* One for every 32KB page in the wal-index */
485 ** Define the parameters of the hash tables in the wal-index file. There
486 ** is a hash-table following every HASHTABLE_NPAGE page numbers in the
489 ** Changing any of these constants will alter the wal-index format and
490 ** create incompatibilities.
492 #define HASHTABLE_NPAGE 4096 /* Must be power of 2 */
493 #define HASHTABLE_HASH_1 383 /* Should be prime */
494 #define HASHTABLE_NSLOT (HASHTABLE_NPAGE*2) /* Must be a power of 2 */
497 ** The block of page numbers associated with the first hash-table in a
498 ** wal-index is smaller than usual. This is so that there is a complete
499 ** hash-table on each aligned 32KB page of the wal-index.
501 #define HASHTABLE_NPAGE_ONE (HASHTABLE_NPAGE - (WALINDEX_HDR_SIZE/sizeof(u32)))
503 /* The wal-index is divided into pages of WALINDEX_PGSZ bytes each. */
504 #define WALINDEX_PGSZ ( \
505 sizeof(ht_slot)*HASHTABLE_NSLOT + HASHTABLE_NPAGE*sizeof(u32) \
509 ** Obtain a pointer to the iPage'th page of the wal-index. The wal-index
510 ** is broken into pages of WALINDEX_PGSZ bytes. Wal-index pages are
511 ** numbered from zero.
513 ** If this call is successful, *ppPage is set to point to the wal-index
514 ** page and SQLITE_OK is returned. If an error (an OOM or VFS error) occurs,
515 ** then an SQLite error code is returned and *ppPage is set to 0.
517 static int walIndexPage(Wal
*pWal
, int iPage
, volatile u32
**ppPage
){
520 /* Enlarge the pWal->apWiData[] array if required */
521 if( pWal
->nWiData
<=iPage
){
522 int nByte
= sizeof(u32
*)*(iPage
+1);
523 volatile u32
**apNew
;
524 apNew
= (volatile u32
**)sqlite3_realloc((void *)pWal
->apWiData
, nByte
);
529 memset((void*)&apNew
[pWal
->nWiData
], 0,
530 sizeof(u32
*)*(iPage
+1-pWal
->nWiData
));
531 pWal
->apWiData
= apNew
;
532 pWal
->nWiData
= iPage
+1;
535 /* Request a pointer to the required page from the VFS */
536 if( pWal
->apWiData
[iPage
]==0 ){
537 if( pWal
->exclusiveMode
==WAL_HEAPMEMORY_MODE
){
538 pWal
->apWiData
[iPage
] = (u32
volatile *)sqlite3MallocZero(WALINDEX_PGSZ
);
539 if( !pWal
->apWiData
[iPage
] ) rc
= SQLITE_NOMEM
;
541 rc
= sqlite3OsShmMap(pWal
->pDbFd
, iPage
, WALINDEX_PGSZ
,
542 pWal
->writeLock
, (void volatile **)&pWal
->apWiData
[iPage
]
544 if( rc
==SQLITE_READONLY
){
545 pWal
->readOnly
|= WAL_SHM_RDONLY
;
551 *ppPage
= pWal
->apWiData
[iPage
];
552 assert( iPage
==0 || *ppPage
|| rc
!=SQLITE_OK
);
557 ** Return a pointer to the WalCkptInfo structure in the wal-index.
559 static volatile WalCkptInfo
*walCkptInfo(Wal
*pWal
){
560 assert( pWal
->nWiData
>0 && pWal
->apWiData
[0] );
561 return (volatile WalCkptInfo
*)&(pWal
->apWiData
[0][sizeof(WalIndexHdr
)/2]);
565 ** Return a pointer to the WalIndexHdr structure in the wal-index.
567 static volatile WalIndexHdr
*walIndexHdr(Wal
*pWal
){
568 assert( pWal
->nWiData
>0 && pWal
->apWiData
[0] );
569 return (volatile WalIndexHdr
*)pWal
->apWiData
[0];
573 ** The argument to this macro must be of type u32. On a little-endian
574 ** architecture, it returns the u32 value that results from interpreting
575 ** the 4 bytes as a big-endian value. On a big-endian architecture, it
576 ** returns the value that would be produced by intepreting the 4 bytes
577 ** of the input value as a little-endian integer.
579 #define BYTESWAP32(x) ( \
580 (((x)&0x000000FF)<<24) + (((x)&0x0000FF00)<<8) \
581 + (((x)&0x00FF0000)>>8) + (((x)&0xFF000000)>>24) \
585 ** Generate or extend an 8 byte checksum based on the data in
586 ** array aByte[] and the initial values of aIn[0] and aIn[1] (or
587 ** initial values of 0 and 0 if aIn==NULL).
589 ** The checksum is written back into aOut[] before returning.
591 ** nByte must be a positive multiple of 8.
593 static void walChecksumBytes(
594 int nativeCksum
, /* True for native byte-order, false for non-native */
595 u8
*a
, /* Content to be checksummed */
596 int nByte
, /* Bytes of content in a[]. Must be a multiple of 8. */
597 const u32
*aIn
, /* Initial checksum value input */
598 u32
*aOut
/* OUT: Final checksum value output */
601 u32
*aData
= (u32
*)a
;
602 u32
*aEnd
= (u32
*)&a
[nByte
];
612 assert( (nByte
&0x00000007)==0 );
618 }while( aData
<aEnd
);
621 s1
+= BYTESWAP32(aData
[0]) + s2
;
622 s2
+= BYTESWAP32(aData
[1]) + s1
;
624 }while( aData
<aEnd
);
631 static void walShmBarrier(Wal
*pWal
){
632 if( pWal
->exclusiveMode
!=WAL_HEAPMEMORY_MODE
){
633 sqlite3OsShmBarrier(pWal
->pDbFd
);
638 ** Write the header information in pWal->hdr into the wal-index.
640 ** The checksum on pWal->hdr is updated before it is written.
642 static void walIndexWriteHdr(Wal
*pWal
){
643 volatile WalIndexHdr
*aHdr
= walIndexHdr(pWal
);
644 const int nCksum
= offsetof(WalIndexHdr
, aCksum
);
646 assert( pWal
->writeLock
);
647 pWal
->hdr
.isInit
= 1;
648 pWal
->hdr
.iVersion
= WALINDEX_MAX_VERSION
;
649 walChecksumBytes(1, (u8
*)&pWal
->hdr
, nCksum
, 0, pWal
->hdr
.aCksum
);
650 memcpy((void *)&aHdr
[1], (void *)&pWal
->hdr
, sizeof(WalIndexHdr
));
652 memcpy((void *)&aHdr
[0], (void *)&pWal
->hdr
, sizeof(WalIndexHdr
));
656 ** This function encodes a single frame header and writes it to a buffer
657 ** supplied by the caller. A frame-header is made up of a series of
658 ** 4-byte big-endian integers, as follows:
661 ** 4: For commit records, the size of the database image in pages
662 ** after the commit. For all other records, zero.
663 ** 8: Salt-1 (copied from the wal-header)
664 ** 12: Salt-2 (copied from the wal-header)
668 static void walEncodeFrame(
669 Wal
*pWal
, /* The write-ahead log */
670 u32 iPage
, /* Database page number for frame */
671 u32 nTruncate
, /* New db size (or 0 for non-commit frames) */
672 u8
*aData
, /* Pointer to page data */
673 u8
*aFrame
/* OUT: Write encoded frame here */
675 int nativeCksum
; /* True for native byte-order checksums */
676 u32
*aCksum
= pWal
->hdr
.aFrameCksum
;
677 assert( WAL_FRAME_HDRSIZE
==24 );
678 sqlite3Put4byte(&aFrame
[0], iPage
);
679 sqlite3Put4byte(&aFrame
[4], nTruncate
);
680 memcpy(&aFrame
[8], pWal
->hdr
.aSalt
, 8);
682 nativeCksum
= (pWal
->hdr
.bigEndCksum
==SQLITE_BIGENDIAN
);
683 walChecksumBytes(nativeCksum
, aFrame
, 8, aCksum
, aCksum
);
684 walChecksumBytes(nativeCksum
, aData
, pWal
->szPage
, aCksum
, aCksum
);
686 sqlite3Put4byte(&aFrame
[16], aCksum
[0]);
687 sqlite3Put4byte(&aFrame
[20], aCksum
[1]);
691 ** Check to see if the frame with header in aFrame[] and content
692 ** in aData[] is valid. If it is a valid frame, fill *piPage and
693 ** *pnTruncate and return true. Return if the frame is not valid.
695 static int walDecodeFrame(
696 Wal
*pWal
, /* The write-ahead log */
697 u32
*piPage
, /* OUT: Database page number for frame */
698 u32
*pnTruncate
, /* OUT: New db size (or 0 if not commit) */
699 u8
*aData
, /* Pointer to page data (for checksum) */
700 u8
*aFrame
/* Frame data */
702 int nativeCksum
; /* True for native byte-order checksums */
703 u32
*aCksum
= pWal
->hdr
.aFrameCksum
;
704 u32 pgno
; /* Page number of the frame */
705 assert( WAL_FRAME_HDRSIZE
==24 );
707 /* A frame is only valid if the salt values in the frame-header
708 ** match the salt values in the wal-header.
710 if( memcmp(&pWal
->hdr
.aSalt
, &aFrame
[8], 8)!=0 ){
714 /* A frame is only valid if the page number is creater than zero.
716 pgno
= sqlite3Get4byte(&aFrame
[0]);
721 /* A frame is only valid if a checksum of the WAL header,
722 ** all prior frams, the first 16 bytes of this frame-header,
723 ** and the frame-data matches the checksum in the last 8
724 ** bytes of this frame-header.
726 nativeCksum
= (pWal
->hdr
.bigEndCksum
==SQLITE_BIGENDIAN
);
727 walChecksumBytes(nativeCksum
, aFrame
, 8, aCksum
, aCksum
);
728 walChecksumBytes(nativeCksum
, aData
, pWal
->szPage
, aCksum
, aCksum
);
729 if( aCksum
[0]!=sqlite3Get4byte(&aFrame
[16])
730 || aCksum
[1]!=sqlite3Get4byte(&aFrame
[20])
732 /* Checksum failed. */
736 /* If we reach this point, the frame is valid. Return the page number
737 ** and the new database size.
740 *pnTruncate
= sqlite3Get4byte(&aFrame
[4]);
745 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
747 ** Names of locks. This routine is used to provide debugging output and is not
748 ** a part of an ordinary build.
750 static const char *walLockName(int lockIdx
){
751 if( lockIdx
==WAL_WRITE_LOCK
){
753 }else if( lockIdx
==WAL_CKPT_LOCK
){
755 }else if( lockIdx
==WAL_RECOVER_LOCK
){
756 return "RECOVER-LOCK";
758 static char zName
[15];
759 sqlite3_snprintf(sizeof(zName
), zName
, "READ-LOCK[%d]",
760 lockIdx
-WAL_READ_LOCK(0));
764 #endif /*defined(SQLITE_TEST) || defined(SQLITE_DEBUG) */
768 ** Set or release locks on the WAL. Locks are either shared or exclusive.
769 ** A lock cannot be moved directly between shared and exclusive - it must go
770 ** through the unlocked state first.
772 ** In locking_mode=EXCLUSIVE, all of these routines become no-ops.
774 static int walLockShared(Wal
*pWal
, int lockIdx
){
776 if( pWal
->exclusiveMode
) return SQLITE_OK
;
777 rc
= sqlite3OsShmLock(pWal
->pDbFd
, lockIdx
, 1,
778 SQLITE_SHM_LOCK
| SQLITE_SHM_SHARED
);
779 WALTRACE(("WAL%p: acquire SHARED-%s %s\n", pWal
,
780 walLockName(lockIdx
), rc
? "failed" : "ok"));
781 VVA_ONLY( pWal
->lockError
= (u8
)(rc
!=SQLITE_OK
&& rc
!=SQLITE_BUSY
); )
784 static void walUnlockShared(Wal
*pWal
, int lockIdx
){
785 if( pWal
->exclusiveMode
) return;
786 (void)sqlite3OsShmLock(pWal
->pDbFd
, lockIdx
, 1,
787 SQLITE_SHM_UNLOCK
| SQLITE_SHM_SHARED
);
788 WALTRACE(("WAL%p: release SHARED-%s\n", pWal
, walLockName(lockIdx
)));
790 static int walLockExclusive(Wal
*pWal
, int lockIdx
, int n
){
792 if( pWal
->exclusiveMode
) return SQLITE_OK
;
793 rc
= sqlite3OsShmLock(pWal
->pDbFd
, lockIdx
, n
,
794 SQLITE_SHM_LOCK
| SQLITE_SHM_EXCLUSIVE
);
795 WALTRACE(("WAL%p: acquire EXCLUSIVE-%s cnt=%d %s\n", pWal
,
796 walLockName(lockIdx
), n
, rc
? "failed" : "ok"));
797 VVA_ONLY( pWal
->lockError
= (u8
)(rc
!=SQLITE_OK
&& rc
!=SQLITE_BUSY
); )
800 static void walUnlockExclusive(Wal
*pWal
, int lockIdx
, int n
){
801 if( pWal
->exclusiveMode
) return;
802 (void)sqlite3OsShmLock(pWal
->pDbFd
, lockIdx
, n
,
803 SQLITE_SHM_UNLOCK
| SQLITE_SHM_EXCLUSIVE
);
804 WALTRACE(("WAL%p: release EXCLUSIVE-%s cnt=%d\n", pWal
,
805 walLockName(lockIdx
), n
));
809 ** Compute a hash on a page number. The resulting hash value must land
810 ** between 0 and (HASHTABLE_NSLOT-1). The walHashNext() function advances
811 ** the hash to the next value in the event of a collision.
813 static int walHash(u32 iPage
){
815 assert( (HASHTABLE_NSLOT
& (HASHTABLE_NSLOT
-1))==0 );
816 return (iPage
*HASHTABLE_HASH_1
) & (HASHTABLE_NSLOT
-1);
818 static int walNextHash(int iPriorHash
){
819 return (iPriorHash
+1)&(HASHTABLE_NSLOT
-1);
823 ** Return pointers to the hash table and page number array stored on
824 ** page iHash of the wal-index. The wal-index is broken into 32KB pages
825 ** numbered starting from 0.
827 ** Set output variable *paHash to point to the start of the hash table
828 ** in the wal-index file. Set *piZero to one less than the frame
829 ** number of the first frame indexed by this hash table. If a
830 ** slot in the hash table is set to N, it refers to frame number
831 ** (*piZero+N) in the log.
833 ** Finally, set *paPgno so that *paPgno[1] is the page number of the
834 ** first frame indexed by the hash table, frame (*piZero+1).
836 static int walHashGet(
837 Wal
*pWal
, /* WAL handle */
838 int iHash
, /* Find the iHash'th table */
839 volatile ht_slot
**paHash
, /* OUT: Pointer to hash index */
840 volatile u32
**paPgno
, /* OUT: Pointer to page number array */
841 u32
*piZero
/* OUT: Frame associated with *paPgno[0] */
843 int rc
; /* Return code */
846 rc
= walIndexPage(pWal
, iHash
, &aPgno
);
847 assert( rc
==SQLITE_OK
|| iHash
>0 );
851 volatile ht_slot
*aHash
;
853 aHash
= (volatile ht_slot
*)&aPgno
[HASHTABLE_NPAGE
];
855 aPgno
= &aPgno
[WALINDEX_HDR_SIZE
/sizeof(u32
)];
858 iZero
= HASHTABLE_NPAGE_ONE
+ (iHash
-1)*HASHTABLE_NPAGE
;
861 *paPgno
= &aPgno
[-1];
869 ** Return the number of the wal-index page that contains the hash-table
870 ** and page-number array that contain entries corresponding to WAL frame
871 ** iFrame. The wal-index is broken up into 32KB pages. Wal-index pages
872 ** are numbered starting from 0.
874 static int walFramePage(u32 iFrame
){
875 int iHash
= (iFrame
+HASHTABLE_NPAGE
-HASHTABLE_NPAGE_ONE
-1) / HASHTABLE_NPAGE
;
876 assert( (iHash
==0 || iFrame
>HASHTABLE_NPAGE_ONE
)
877 && (iHash
>=1 || iFrame
<=HASHTABLE_NPAGE_ONE
)
878 && (iHash
<=1 || iFrame
>(HASHTABLE_NPAGE_ONE
+HASHTABLE_NPAGE
))
879 && (iHash
>=2 || iFrame
<=HASHTABLE_NPAGE_ONE
+HASHTABLE_NPAGE
)
880 && (iHash
<=2 || iFrame
>(HASHTABLE_NPAGE_ONE
+2*HASHTABLE_NPAGE
))
886 ** Return the page number associated with frame iFrame in this WAL.
888 static u32
walFramePgno(Wal
*pWal
, u32 iFrame
){
889 int iHash
= walFramePage(iFrame
);
891 return pWal
->apWiData
[0][WALINDEX_HDR_SIZE
/sizeof(u32
) + iFrame
- 1];
893 return pWal
->apWiData
[iHash
][(iFrame
-1-HASHTABLE_NPAGE_ONE
)%HASHTABLE_NPAGE
];
897 ** Remove entries from the hash table that point to WAL slots greater
898 ** than pWal->hdr.mxFrame.
900 ** This function is called whenever pWal->hdr.mxFrame is decreased due
901 ** to a rollback or savepoint.
903 ** At most only the hash table containing pWal->hdr.mxFrame needs to be
904 ** updated. Any later hash tables will be automatically cleared when
905 ** pWal->hdr.mxFrame advances to the point where those hash tables are
908 static void walCleanupHash(Wal
*pWal
){
909 volatile ht_slot
*aHash
= 0; /* Pointer to hash table to clear */
910 volatile u32
*aPgno
= 0; /* Page number array for hash table */
911 u32 iZero
= 0; /* frame == (aHash[x]+iZero) */
912 int iLimit
= 0; /* Zero values greater than this */
913 int nByte
; /* Number of bytes to zero in aPgno[] */
914 int i
; /* Used to iterate through aHash[] */
916 assert( pWal
->writeLock
);
917 testcase( pWal
->hdr
.mxFrame
==HASHTABLE_NPAGE_ONE
-1 );
918 testcase( pWal
->hdr
.mxFrame
==HASHTABLE_NPAGE_ONE
);
919 testcase( pWal
->hdr
.mxFrame
==HASHTABLE_NPAGE_ONE
+1 );
921 if( pWal
->hdr
.mxFrame
==0 ) return;
923 /* Obtain pointers to the hash-table and page-number array containing
924 ** the entry that corresponds to frame pWal->hdr.mxFrame. It is guaranteed
925 ** that the page said hash-table and array reside on is already mapped.
927 assert( pWal
->nWiData
>walFramePage(pWal
->hdr
.mxFrame
) );
928 assert( pWal
->apWiData
[walFramePage(pWal
->hdr
.mxFrame
)] );
929 walHashGet(pWal
, walFramePage(pWal
->hdr
.mxFrame
), &aHash
, &aPgno
, &iZero
);
931 /* Zero all hash-table entries that correspond to frame numbers greater
932 ** than pWal->hdr.mxFrame.
934 iLimit
= pWal
->hdr
.mxFrame
- iZero
;
936 for(i
=0; i
<HASHTABLE_NSLOT
; i
++){
937 if( aHash
[i
]>iLimit
){
942 /* Zero the entries in the aPgno array that correspond to frames with
943 ** frame numbers greater than pWal->hdr.mxFrame.
945 nByte
= (int)((char *)aHash
- (char *)&aPgno
[iLimit
+1]);
946 memset((void *)&aPgno
[iLimit
+1], 0, nByte
);
948 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
949 /* Verify that the every entry in the mapping region is still reachable
950 ** via the hash table even after the cleanup.
953 int i
; /* Loop counter */
954 int iKey
; /* Hash key */
955 for(i
=1; i
<=iLimit
; i
++){
956 for(iKey
=walHash(aPgno
[i
]); aHash
[iKey
]; iKey
=walNextHash(iKey
)){
957 if( aHash
[iKey
]==i
) break;
959 assert( aHash
[iKey
]==i
);
962 #endif /* SQLITE_ENABLE_EXPENSIVE_ASSERT */
967 ** Set an entry in the wal-index that will map database page number
968 ** pPage into WAL frame iFrame.
970 static int walIndexAppend(Wal
*pWal
, u32 iFrame
, u32 iPage
){
971 int rc
; /* Return code */
972 u32 iZero
= 0; /* One less than frame number of aPgno[1] */
973 volatile u32
*aPgno
= 0; /* Page number array */
974 volatile ht_slot
*aHash
= 0; /* Hash table */
976 rc
= walHashGet(pWal
, walFramePage(iFrame
), &aHash
, &aPgno
, &iZero
);
978 /* Assuming the wal-index file was successfully mapped, populate the
979 ** page number array and hash table entry.
982 int iKey
; /* Hash table key */
983 int idx
; /* Value to write to hash-table slot */
984 int nCollide
; /* Number of hash collisions */
986 idx
= iFrame
- iZero
;
987 assert( idx
<= HASHTABLE_NSLOT
/2 + 1 );
989 /* If this is the first entry to be added to this hash-table, zero the
990 ** entire hash table and aPgno[] array before proceding.
993 int nByte
= (int)((u8
*)&aHash
[HASHTABLE_NSLOT
] - (u8
*)&aPgno
[1]);
994 memset((void*)&aPgno
[1], 0, nByte
);
997 /* If the entry in aPgno[] is already set, then the previous writer
998 ** must have exited unexpectedly in the middle of a transaction (after
999 ** writing one or more dirty pages to the WAL to free up memory).
1000 ** Remove the remnants of that writers uncommitted transaction from
1001 ** the hash-table before writing any new entries.
1004 walCleanupHash(pWal
);
1005 assert( !aPgno
[idx
] );
1008 /* Write the aPgno[] array entry and the hash-table slot. */
1010 for(iKey
=walHash(iPage
); aHash
[iKey
]; iKey
=walNextHash(iKey
)){
1011 if( (nCollide
--)==0 ) return SQLITE_CORRUPT_BKPT
;
1014 aHash
[iKey
] = (ht_slot
)idx
;
1016 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
1017 /* Verify that the number of entries in the hash table exactly equals
1018 ** the number of entries in the mapping region.
1021 int i
; /* Loop counter */
1022 int nEntry
= 0; /* Number of entries in the hash table */
1023 for(i
=0; i
<HASHTABLE_NSLOT
; i
++){ if( aHash
[i
] ) nEntry
++; }
1024 assert( nEntry
==idx
);
1027 /* Verify that the every entry in the mapping region is reachable
1028 ** via the hash table. This turns out to be a really, really expensive
1029 ** thing to check, so only do this occasionally - not on every
1032 if( (idx
&0x3ff)==0 ){
1033 int i
; /* Loop counter */
1034 for(i
=1; i
<=idx
; i
++){
1035 for(iKey
=walHash(aPgno
[i
]); aHash
[iKey
]; iKey
=walNextHash(iKey
)){
1036 if( aHash
[iKey
]==i
) break;
1038 assert( aHash
[iKey
]==i
);
1041 #endif /* SQLITE_ENABLE_EXPENSIVE_ASSERT */
1050 ** Recover the wal-index by reading the write-ahead log file.
1052 ** This routine first tries to establish an exclusive lock on the
1053 ** wal-index to prevent other threads/processes from doing anything
1054 ** with the WAL or wal-index while recovery is running. The
1055 ** WAL_RECOVER_LOCK is also held so that other threads will know
1056 ** that this thread is running recovery. If unable to establish
1057 ** the necessary locks, this routine returns SQLITE_BUSY.
1059 static int walIndexRecover(Wal
*pWal
){
1060 int rc
; /* Return Code */
1061 i64 nSize
; /* Size of log file */
1062 u32 aFrameCksum
[2] = {0, 0};
1063 int iLock
; /* Lock offset to lock for checkpoint */
1064 int nLock
; /* Number of locks to hold */
1066 /* Obtain an exclusive lock on all byte in the locking range not already
1067 ** locked by the caller. The caller is guaranteed to have locked the
1068 ** WAL_WRITE_LOCK byte, and may have also locked the WAL_CKPT_LOCK byte.
1069 ** If successful, the same bytes that are locked here are unlocked before
1070 ** this function returns.
1072 assert( pWal
->ckptLock
==1 || pWal
->ckptLock
==0 );
1073 assert( WAL_ALL_BUT_WRITE
==WAL_WRITE_LOCK
+1 );
1074 assert( WAL_CKPT_LOCK
==WAL_ALL_BUT_WRITE
);
1075 assert( pWal
->writeLock
);
1076 iLock
= WAL_ALL_BUT_WRITE
+ pWal
->ckptLock
;
1077 nLock
= SQLITE_SHM_NLOCK
- iLock
;
1078 rc
= walLockExclusive(pWal
, iLock
, nLock
);
1082 WALTRACE(("WAL%p: recovery begin...\n", pWal
));
1084 memset(&pWal
->hdr
, 0, sizeof(WalIndexHdr
));
1086 rc
= sqlite3OsFileSize(pWal
->pWalFd
, &nSize
);
1087 if( rc
!=SQLITE_OK
){
1088 goto recovery_error
;
1091 if( nSize
>WAL_HDRSIZE
){
1092 u8 aBuf
[WAL_HDRSIZE
]; /* Buffer to load WAL header into */
1093 u8
*aFrame
= 0; /* Malloc'd buffer to load entire frame */
1094 int szFrame
; /* Number of bytes in buffer aFrame[] */
1095 u8
*aData
; /* Pointer to data part of aFrame buffer */
1096 int iFrame
; /* Index of last frame read */
1097 i64 iOffset
; /* Next offset to read from log file */
1098 int szPage
; /* Page size according to the log */
1099 u32 magic
; /* Magic value read from WAL header */
1100 u32 version
; /* Magic value read from WAL header */
1101 int isValid
; /* True if this frame is valid */
1103 /* Read in the WAL header. */
1104 rc
= sqlite3OsRead(pWal
->pWalFd
, aBuf
, WAL_HDRSIZE
, 0);
1105 if( rc
!=SQLITE_OK
){
1106 goto recovery_error
;
1109 /* If the database page size is not a power of two, or is greater than
1110 ** SQLITE_MAX_PAGE_SIZE, conclude that the WAL file contains no valid
1111 ** data. Similarly, if the 'magic' value is invalid, ignore the whole
1114 magic
= sqlite3Get4byte(&aBuf
[0]);
1115 szPage
= sqlite3Get4byte(&aBuf
[8]);
1116 if( (magic
&0xFFFFFFFE)!=WAL_MAGIC
1117 || szPage
&(szPage
-1)
1118 || szPage
>SQLITE_MAX_PAGE_SIZE
1123 pWal
->hdr
.bigEndCksum
= (u8
)(magic
&0x00000001);
1124 pWal
->szPage
= szPage
;
1125 pWal
->nCkpt
= sqlite3Get4byte(&aBuf
[12]);
1126 memcpy(&pWal
->hdr
.aSalt
, &aBuf
[16], 8);
1128 /* Verify that the WAL header checksum is correct */
1129 walChecksumBytes(pWal
->hdr
.bigEndCksum
==SQLITE_BIGENDIAN
,
1130 aBuf
, WAL_HDRSIZE
-2*4, 0, pWal
->hdr
.aFrameCksum
1132 if( pWal
->hdr
.aFrameCksum
[0]!=sqlite3Get4byte(&aBuf
[24])
1133 || pWal
->hdr
.aFrameCksum
[1]!=sqlite3Get4byte(&aBuf
[28])
1138 /* Verify that the version number on the WAL format is one that
1139 ** are able to understand */
1140 version
= sqlite3Get4byte(&aBuf
[4]);
1141 if( version
!=WAL_MAX_VERSION
){
1142 rc
= SQLITE_CANTOPEN_BKPT
;
1146 /* Malloc a buffer to read frames into. */
1147 szFrame
= szPage
+ WAL_FRAME_HDRSIZE
;
1148 aFrame
= (u8
*)sqlite3_malloc(szFrame
);
1151 goto recovery_error
;
1153 aData
= &aFrame
[WAL_FRAME_HDRSIZE
];
1155 /* Read all frames from the log file. */
1157 for(iOffset
=WAL_HDRSIZE
; (iOffset
+szFrame
)<=nSize
; iOffset
+=szFrame
){
1158 u32 pgno
; /* Database page number for frame */
1159 u32 nTruncate
; /* dbsize field from frame header */
1161 /* Read and decode the next log frame. */
1163 rc
= sqlite3OsRead(pWal
->pWalFd
, aFrame
, szFrame
, iOffset
);
1164 if( rc
!=SQLITE_OK
) break;
1165 isValid
= walDecodeFrame(pWal
, &pgno
, &nTruncate
, aData
, aFrame
);
1166 if( !isValid
) break;
1167 rc
= walIndexAppend(pWal
, iFrame
, pgno
);
1168 if( rc
!=SQLITE_OK
) break;
1170 /* If nTruncate is non-zero, this is a commit record. */
1172 pWal
->hdr
.mxFrame
= iFrame
;
1173 pWal
->hdr
.nPage
= nTruncate
;
1174 pWal
->hdr
.szPage
= (u16
)((szPage
&0xff00) | (szPage
>>16));
1175 testcase( szPage
<=32768 );
1176 testcase( szPage
>=65536 );
1177 aFrameCksum
[0] = pWal
->hdr
.aFrameCksum
[0];
1178 aFrameCksum
[1] = pWal
->hdr
.aFrameCksum
[1];
1182 sqlite3_free(aFrame
);
1186 if( rc
==SQLITE_OK
){
1187 volatile WalCkptInfo
*pInfo
;
1189 pWal
->hdr
.aFrameCksum
[0] = aFrameCksum
[0];
1190 pWal
->hdr
.aFrameCksum
[1] = aFrameCksum
[1];
1191 walIndexWriteHdr(pWal
);
1193 /* Reset the checkpoint-header. This is safe because this thread is
1194 ** currently holding locks that exclude all other readers, writers and
1197 pInfo
= walCkptInfo(pWal
);
1198 pInfo
->nBackfill
= 0;
1199 pInfo
->aReadMark
[0] = 0;
1200 for(i
=1; i
<WAL_NREADER
; i
++) pInfo
->aReadMark
[i
] = READMARK_NOT_USED
;
1202 /* If more than one frame was recovered from the log file, report an
1203 ** event via sqlite3_log(). This is to help with identifying performance
1204 ** problems caused by applications routinely shutting down without
1205 ** checkpointing the log file.
1207 if( pWal
->hdr
.nPage
){
1208 sqlite3_log(SQLITE_OK
, "Recovered %d frames from WAL file %s",
1209 pWal
->hdr
.nPage
, pWal
->zWalName
1215 WALTRACE(("WAL%p: recovery %s\n", pWal
, rc
? "failed" : "ok"));
1216 walUnlockExclusive(pWal
, iLock
, nLock
);
1221 ** Close an open wal-index.
1223 static void walIndexClose(Wal
*pWal
, int isDelete
){
1224 if( pWal
->exclusiveMode
==WAL_HEAPMEMORY_MODE
){
1226 for(i
=0; i
<pWal
->nWiData
; i
++){
1227 sqlite3_free((void *)pWal
->apWiData
[i
]);
1228 pWal
->apWiData
[i
] = 0;
1231 sqlite3OsShmUnmap(pWal
->pDbFd
, isDelete
);
1236 ** Open a connection to the WAL file zWalName. The database file must
1237 ** already be opened on connection pDbFd. The buffer that zWalName points
1238 ** to must remain valid for the lifetime of the returned Wal* handle.
1240 ** A SHARED lock should be held on the database file when this function
1241 ** is called. The purpose of this SHARED lock is to prevent any other
1242 ** client from unlinking the WAL or wal-index file. If another process
1243 ** were to do this just after this client opened one of these files, the
1244 ** system would be badly broken.
1246 ** If the log file is successfully opened, SQLITE_OK is returned and
1247 ** *ppWal is set to point to a new WAL handle. If an error occurs,
1248 ** an SQLite error code is returned and *ppWal is left unmodified.
1251 sqlite3_vfs
*pVfs
, /* vfs module to open wal and wal-index */
1252 sqlite3_file
*pDbFd
, /* The open database file */
1253 const char *zWalName
, /* Name of the WAL file */
1254 int bNoShm
, /* True to run in heap-memory mode */
1255 i64 mxWalSize
, /* Truncate WAL to this size on reset */
1256 Wal
**ppWal
/* OUT: Allocated Wal handle */
1258 int rc
; /* Return Code */
1259 Wal
*pRet
; /* Object to allocate and return */
1260 int flags
; /* Flags passed to OsOpen() */
1262 assert( zWalName
&& zWalName
[0] );
1265 /* In the amalgamation, the os_unix.c and os_win.c source files come before
1266 ** this source file. Verify that the #defines of the locking byte offsets
1267 ** in os_unix.c and os_win.c agree with the WALINDEX_LOCK_OFFSET value.
1270 assert( WIN_SHM_BASE
==WALINDEX_LOCK_OFFSET
);
1272 #ifdef UNIX_SHM_BASE
1273 assert( UNIX_SHM_BASE
==WALINDEX_LOCK_OFFSET
);
1277 /* Allocate an instance of struct Wal to return. */
1279 pRet
= (Wal
*)sqlite3MallocZero(sizeof(Wal
) + pVfs
->szOsFile
);
1281 return SQLITE_NOMEM
;
1285 pRet
->pWalFd
= (sqlite3_file
*)&pRet
[1];
1286 pRet
->pDbFd
= pDbFd
;
1287 pRet
->readLock
= -1;
1288 pRet
->mxWalSize
= mxWalSize
;
1289 pRet
->zWalName
= zWalName
;
1290 pRet
->syncHeader
= 1;
1291 pRet
->padToSectorBoundary
= 1;
1292 pRet
->exclusiveMode
= (bNoShm
? WAL_HEAPMEMORY_MODE
: WAL_NORMAL_MODE
);
1294 /* Open file handle on the write-ahead log file. */
1295 flags
= (SQLITE_OPEN_READWRITE
|SQLITE_OPEN_CREATE
|SQLITE_OPEN_WAL
);
1296 rc
= sqlite3OsOpen(pVfs
, zWalName
, pRet
->pWalFd
, flags
, &flags
);
1297 if( rc
==SQLITE_OK
&& flags
&SQLITE_OPEN_READONLY
){
1298 pRet
->readOnly
= WAL_RDONLY
;
1301 if( rc
!=SQLITE_OK
){
1302 walIndexClose(pRet
, 0);
1303 sqlite3OsClose(pRet
->pWalFd
);
1306 int iDC
= sqlite3OsDeviceCharacteristics(pRet
->pWalFd
);
1307 if( iDC
& SQLITE_IOCAP_SEQUENTIAL
){ pRet
->syncHeader
= 0; }
1308 if( iDC
& SQLITE_IOCAP_POWERSAFE_OVERWRITE
){
1309 pRet
->padToSectorBoundary
= 0;
1312 WALTRACE(("WAL%d: opened\n", pRet
));
1318 ** Change the size to which the WAL file is trucated on each reset.
1320 void sqlite3WalLimit(Wal
*pWal
, i64 iLimit
){
1321 if( pWal
) pWal
->mxWalSize
= iLimit
;
1325 ** Find the smallest page number out of all pages held in the WAL that
1326 ** has not been returned by any prior invocation of this method on the
1327 ** same WalIterator object. Write into *piFrame the frame index where
1328 ** that page was last written into the WAL. Write into *piPage the page
1331 ** Return 0 on success. If there are no pages in the WAL with a page
1332 ** number larger than *piPage, then return 1.
1334 static int walIteratorNext(
1335 WalIterator
*p
, /* Iterator */
1336 u32
*piPage
, /* OUT: The page number of the next page */
1337 u32
*piFrame
/* OUT: Wal frame index of next page */
1339 u32 iMin
; /* Result pgno must be greater than iMin */
1340 u32 iRet
= 0xFFFFFFFF; /* 0xffffffff is never a valid page number */
1341 int i
; /* For looping through segments */
1344 assert( iMin
<0xffffffff );
1345 for(i
=p
->nSegment
-1; i
>=0; i
--){
1346 struct WalSegment
*pSegment
= &p
->aSegment
[i
];
1347 while( pSegment
->iNext
<pSegment
->nEntry
){
1348 u32 iPg
= pSegment
->aPgno
[pSegment
->aIndex
[pSegment
->iNext
]];
1352 *piFrame
= pSegment
->iZero
+ pSegment
->aIndex
[pSegment
->iNext
];
1360 *piPage
= p
->iPrior
= iRet
;
1361 return (iRet
==0xFFFFFFFF);
1365 ** This function merges two sorted lists into a single sorted list.
1367 ** aLeft[] and aRight[] are arrays of indices. The sort key is
1368 ** aContent[aLeft[]] and aContent[aRight[]]. Upon entry, the following
1369 ** is guaranteed for all J<K:
1371 ** aContent[aLeft[J]] < aContent[aLeft[K]]
1372 ** aContent[aRight[J]] < aContent[aRight[K]]
1374 ** This routine overwrites aRight[] with a new (probably longer) sequence
1375 ** of indices such that the aRight[] contains every index that appears in
1376 ** either aLeft[] or the old aRight[] and such that the second condition
1377 ** above is still met.
1379 ** The aContent[aLeft[X]] values will be unique for all X. And the
1380 ** aContent[aRight[X]] values will be unique too. But there might be
1381 ** one or more combinations of X and Y such that
1383 ** aLeft[X]!=aRight[Y] && aContent[aLeft[X]] == aContent[aRight[Y]]
1385 ** When that happens, omit the aLeft[X] and use the aRight[Y] index.
1387 static void walMerge(
1388 const u32
*aContent
, /* Pages in wal - keys for the sort */
1389 ht_slot
*aLeft
, /* IN: Left hand input list */
1390 int nLeft
, /* IN: Elements in array *paLeft */
1391 ht_slot
**paRight
, /* IN/OUT: Right hand input list */
1392 int *pnRight
, /* IN/OUT: Elements in *paRight */
1393 ht_slot
*aTmp
/* Temporary buffer */
1395 int iLeft
= 0; /* Current index in aLeft */
1396 int iRight
= 0; /* Current index in aRight */
1397 int iOut
= 0; /* Current index in output buffer */
1398 int nRight
= *pnRight
;
1399 ht_slot
*aRight
= *paRight
;
1401 assert( nLeft
>0 && nRight
>0 );
1402 while( iRight
<nRight
|| iLeft
<nLeft
){
1407 && (iRight
>=nRight
|| aContent
[aLeft
[iLeft
]]<aContent
[aRight
[iRight
]])
1409 logpage
= aLeft
[iLeft
++];
1411 logpage
= aRight
[iRight
++];
1413 dbpage
= aContent
[logpage
];
1415 aTmp
[iOut
++] = logpage
;
1416 if( iLeft
<nLeft
&& aContent
[aLeft
[iLeft
]]==dbpage
) iLeft
++;
1418 assert( iLeft
>=nLeft
|| aContent
[aLeft
[iLeft
]]>dbpage
);
1419 assert( iRight
>=nRight
|| aContent
[aRight
[iRight
]]>dbpage
);
1424 memcpy(aLeft
, aTmp
, sizeof(aTmp
[0])*iOut
);
1428 ** Sort the elements in list aList using aContent[] as the sort key.
1429 ** Remove elements with duplicate keys, preferring to keep the
1430 ** larger aList[] values.
1432 ** The aList[] entries are indices into aContent[]. The values in
1433 ** aList[] are to be sorted so that for all J<K:
1435 ** aContent[aList[J]] < aContent[aList[K]]
1437 ** For any X and Y such that
1439 ** aContent[aList[X]] == aContent[aList[Y]]
1441 ** Keep the larger of the two values aList[X] and aList[Y] and discard
1444 static void walMergesort(
1445 const u32
*aContent
, /* Pages in wal */
1446 ht_slot
*aBuffer
, /* Buffer of at least *pnList items to use */
1447 ht_slot
*aList
, /* IN/OUT: List to sort */
1448 int *pnList
/* IN/OUT: Number of elements in aList[] */
1451 int nList
; /* Number of elements in aList */
1452 ht_slot
*aList
; /* Pointer to sub-list content */
1455 const int nList
= *pnList
; /* Size of input list */
1456 int nMerge
= 0; /* Number of elements in list aMerge */
1457 ht_slot
*aMerge
= 0; /* List to be merged */
1458 int iList
; /* Index into input list */
1459 int iSub
= 0; /* Index into aSub array */
1460 struct Sublist aSub
[13]; /* Array of sub-lists */
1462 memset(aSub
, 0, sizeof(aSub
));
1463 assert( nList
<=HASHTABLE_NPAGE
&& nList
>0 );
1464 assert( HASHTABLE_NPAGE
==(1<<(ArraySize(aSub
)-1)) );
1466 for(iList
=0; iList
<nList
; iList
++){
1468 aMerge
= &aList
[iList
];
1469 for(iSub
=0; iList
& (1<<iSub
); iSub
++){
1470 struct Sublist
*p
= &aSub
[iSub
];
1471 assert( p
->aList
&& p
->nList
<=(1<<iSub
) );
1472 assert( p
->aList
==&aList
[iList
&~((2<<iSub
)-1)] );
1473 walMerge(aContent
, p
->aList
, p
->nList
, &aMerge
, &nMerge
, aBuffer
);
1475 aSub
[iSub
].aList
= aMerge
;
1476 aSub
[iSub
].nList
= nMerge
;
1479 for(iSub
++; iSub
<ArraySize(aSub
); iSub
++){
1480 if( nList
& (1<<iSub
) ){
1481 struct Sublist
*p
= &aSub
[iSub
];
1482 assert( p
->nList
<=(1<<iSub
) );
1483 assert( p
->aList
==&aList
[nList
&~((2<<iSub
)-1)] );
1484 walMerge(aContent
, p
->aList
, p
->nList
, &aMerge
, &nMerge
, aBuffer
);
1487 assert( aMerge
==aList
);
1493 for(i
=1; i
<*pnList
; i
++){
1494 assert( aContent
[aList
[i
]] > aContent
[aList
[i
-1]] );
1501 ** Free an iterator allocated by walIteratorInit().
1503 static void walIteratorFree(WalIterator
*p
){
1504 sqlite3ScratchFree(p
);
1508 ** Construct a WalInterator object that can be used to loop over all
1509 ** pages in the WAL in ascending order. The caller must hold the checkpoint
1512 ** On success, make *pp point to the newly allocated WalInterator object
1513 ** return SQLITE_OK. Otherwise, return an error code. If this routine
1514 ** returns an error, the value of *pp is undefined.
1516 ** The calling routine should invoke walIteratorFree() to destroy the
1517 ** WalIterator object when it has finished with it.
1519 static int walIteratorInit(Wal
*pWal
, WalIterator
**pp
){
1520 WalIterator
*p
; /* Return value */
1521 int nSegment
; /* Number of segments to merge */
1522 u32 iLast
; /* Last frame in log */
1523 int nByte
; /* Number of bytes to allocate */
1524 int i
; /* Iterator variable */
1525 ht_slot
*aTmp
; /* Temp space used by merge-sort */
1526 int rc
= SQLITE_OK
; /* Return Code */
1528 /* This routine only runs while holding the checkpoint lock. And
1529 ** it only runs if there is actually content in the log (mxFrame>0).
1531 assert( pWal
->ckptLock
&& pWal
->hdr
.mxFrame
>0 );
1532 iLast
= pWal
->hdr
.mxFrame
;
1534 /* Allocate space for the WalIterator object. */
1535 nSegment
= walFramePage(iLast
) + 1;
1536 nByte
= sizeof(WalIterator
)
1537 + (nSegment
-1)*sizeof(struct WalSegment
)
1538 + iLast
*sizeof(ht_slot
);
1539 p
= (WalIterator
*)sqlite3ScratchMalloc(nByte
);
1541 return SQLITE_NOMEM
;
1543 memset(p
, 0, nByte
);
1544 p
->nSegment
= nSegment
;
1546 /* Allocate temporary space used by the merge-sort routine. This block
1547 ** of memory will be freed before this function returns.
1549 aTmp
= (ht_slot
*)sqlite3ScratchMalloc(
1550 sizeof(ht_slot
) * (iLast
>HASHTABLE_NPAGE
?HASHTABLE_NPAGE
:iLast
)
1556 for(i
=0; rc
==SQLITE_OK
&& i
<nSegment
; i
++){
1557 volatile ht_slot
*aHash
;
1559 volatile u32
*aPgno
;
1561 rc
= walHashGet(pWal
, i
, &aHash
, &aPgno
, &iZero
);
1562 if( rc
==SQLITE_OK
){
1563 int j
; /* Counter variable */
1564 int nEntry
; /* Number of entries in this segment */
1565 ht_slot
*aIndex
; /* Sorted index for this segment */
1568 if( (i
+1)==nSegment
){
1569 nEntry
= (int)(iLast
- iZero
);
1571 nEntry
= (int)((u32
*)aHash
- (u32
*)aPgno
);
1573 aIndex
= &((ht_slot
*)&p
->aSegment
[p
->nSegment
])[iZero
];
1576 for(j
=0; j
<nEntry
; j
++){
1577 aIndex
[j
] = (ht_slot
)j
;
1579 walMergesort((u32
*)aPgno
, aTmp
, aIndex
, &nEntry
);
1580 p
->aSegment
[i
].iZero
= iZero
;
1581 p
->aSegment
[i
].nEntry
= nEntry
;
1582 p
->aSegment
[i
].aIndex
= aIndex
;
1583 p
->aSegment
[i
].aPgno
= (u32
*)aPgno
;
1586 sqlite3ScratchFree(aTmp
);
1588 if( rc
!=SQLITE_OK
){
1596 ** Attempt to obtain the exclusive WAL lock defined by parameters lockIdx and
1597 ** n. If the attempt fails and parameter xBusy is not NULL, then it is a
1598 ** busy-handler function. Invoke it and retry the lock until either the
1599 ** lock is successfully obtained or the busy-handler returns 0.
1601 static int walBusyLock(
1602 Wal
*pWal
, /* WAL connection */
1603 int (*xBusy
)(void*), /* Function to call when busy */
1604 void *pBusyArg
, /* Context argument for xBusyHandler */
1605 int lockIdx
, /* Offset of first byte to lock */
1606 int n
/* Number of bytes to lock */
1610 rc
= walLockExclusive(pWal
, lockIdx
, n
);
1611 }while( xBusy
&& rc
==SQLITE_BUSY
&& xBusy(pBusyArg
) );
1616 ** The cache of the wal-index header must be valid to call this function.
1617 ** Return the page-size in bytes used by the database.
1619 static int walPagesize(Wal
*pWal
){
1620 return (pWal
->hdr
.szPage
&0xfe00) + ((pWal
->hdr
.szPage
&0x0001)<<16);
1624 ** Copy as much content as we can from the WAL back into the database file
1625 ** in response to an sqlite3_wal_checkpoint() request or the equivalent.
1627 ** The amount of information copies from WAL to database might be limited
1628 ** by active readers. This routine will never overwrite a database page
1629 ** that a concurrent reader might be using.
1631 ** All I/O barrier operations (a.k.a fsyncs) occur in this routine when
1632 ** SQLite is in WAL-mode in synchronous=NORMAL. That means that if
1633 ** checkpoints are always run by a background thread or background
1634 ** process, foreground threads will never block on a lengthy fsync call.
1636 ** Fsync is called on the WAL before writing content out of the WAL and
1637 ** into the database. This ensures that if the new content is persistent
1638 ** in the WAL and can be recovered following a power-loss or hard reset.
1640 ** Fsync is also called on the database file if (and only if) the entire
1641 ** WAL content is copied into the database file. This second fsync makes
1642 ** it safe to delete the WAL since the new content will persist in the
1645 ** This routine uses and updates the nBackfill field of the wal-index header.
1646 ** This is the only routine tha will increase the value of nBackfill.
1647 ** (A WAL reset or recovery will revert nBackfill to zero, but not increase
1650 ** The caller must be holding sufficient locks to ensure that no other
1651 ** checkpoint is running (in any other thread or process) at the same
1654 static int walCheckpoint(
1655 Wal
*pWal
, /* Wal connection */
1656 int eMode
, /* One of PASSIVE, FULL or RESTART */
1657 int (*xBusyCall
)(void*), /* Function to call when busy */
1658 void *pBusyArg
, /* Context argument for xBusyHandler */
1659 int sync_flags
, /* Flags for OsSync() (or 0) */
1660 u8
*zBuf
/* Temporary buffer to use */
1662 int rc
; /* Return code */
1663 int szPage
; /* Database page-size */
1664 WalIterator
*pIter
= 0; /* Wal iterator context */
1665 u32 iDbpage
= 0; /* Next database page to write */
1666 u32 iFrame
= 0; /* Wal frame containing data for iDbpage */
1667 u32 mxSafeFrame
; /* Max frame that can be backfilled */
1668 u32 mxPage
; /* Max database page to write */
1669 int i
; /* Loop counter */
1670 volatile WalCkptInfo
*pInfo
; /* The checkpoint status information */
1671 int (*xBusy
)(void*) = 0; /* Function to call when waiting for locks */
1673 szPage
= walPagesize(pWal
);
1674 testcase( szPage
<=32768 );
1675 testcase( szPage
>=65536 );
1676 pInfo
= walCkptInfo(pWal
);
1677 if( pInfo
->nBackfill
>=pWal
->hdr
.mxFrame
) return SQLITE_OK
;
1679 /* Allocate the iterator */
1680 rc
= walIteratorInit(pWal
, &pIter
);
1681 if( rc
!=SQLITE_OK
){
1686 if( eMode
!=SQLITE_CHECKPOINT_PASSIVE
) xBusy
= xBusyCall
;
1688 /* Compute in mxSafeFrame the index of the last frame of the WAL that is
1689 ** safe to write into the database. Frames beyond mxSafeFrame might
1690 ** overwrite database pages that are in use by active readers and thus
1691 ** cannot be backfilled from the WAL.
1693 mxSafeFrame
= pWal
->hdr
.mxFrame
;
1694 mxPage
= pWal
->hdr
.nPage
;
1695 for(i
=1; i
<WAL_NREADER
; i
++){
1696 u32 y
= pInfo
->aReadMark
[i
];
1697 if( mxSafeFrame
>y
){
1698 assert( y
<=pWal
->hdr
.mxFrame
);
1699 rc
= walBusyLock(pWal
, xBusy
, pBusyArg
, WAL_READ_LOCK(i
), 1);
1700 if( rc
==SQLITE_OK
){
1701 pInfo
->aReadMark
[i
] = READMARK_NOT_USED
;
1702 walUnlockExclusive(pWal
, WAL_READ_LOCK(i
), 1);
1703 }else if( rc
==SQLITE_BUSY
){
1707 goto walcheckpoint_out
;
1712 if( pInfo
->nBackfill
<mxSafeFrame
1713 && (rc
= walBusyLock(pWal
, xBusy
, pBusyArg
, WAL_READ_LOCK(0), 1))==SQLITE_OK
1715 i64 nSize
; /* Current size of database file */
1716 u32 nBackfill
= pInfo
->nBackfill
;
1718 /* Sync the WAL to disk */
1720 rc
= sqlite3OsSync(pWal
->pWalFd
, sync_flags
);
1723 /* If the database file may grow as a result of this checkpoint, hint
1724 ** about the eventual size of the db file to the VFS layer.
1726 if( rc
==SQLITE_OK
){
1727 i64 nReq
= ((i64
)mxPage
* szPage
);
1728 rc
= sqlite3OsFileSize(pWal
->pDbFd
, &nSize
);
1729 if( rc
==SQLITE_OK
&& nSize
<nReq
){
1730 sqlite3OsFileControlHint(pWal
->pDbFd
, SQLITE_FCNTL_SIZE_HINT
, &nReq
);
1734 /* Iterate through the contents of the WAL, copying data to the db file. */
1735 while( rc
==SQLITE_OK
&& 0==walIteratorNext(pIter
, &iDbpage
, &iFrame
) ){
1737 assert( walFramePgno(pWal
, iFrame
)==iDbpage
);
1738 if( iFrame
<=nBackfill
|| iFrame
>mxSafeFrame
|| iDbpage
>mxPage
) continue;
1739 iOffset
= walFrameOffset(iFrame
, szPage
) + WAL_FRAME_HDRSIZE
;
1740 /* testcase( IS_BIG_INT(iOffset) ); // requires a 4GiB WAL file */
1741 rc
= sqlite3OsRead(pWal
->pWalFd
, zBuf
, szPage
, iOffset
);
1742 if( rc
!=SQLITE_OK
) break;
1743 iOffset
= (iDbpage
-1)*(i64
)szPage
;
1744 testcase( IS_BIG_INT(iOffset
) );
1745 rc
= sqlite3OsWrite(pWal
->pDbFd
, zBuf
, szPage
, iOffset
);
1746 if( rc
!=SQLITE_OK
) break;
1749 /* If work was actually accomplished... */
1750 if( rc
==SQLITE_OK
){
1751 if( mxSafeFrame
==walIndexHdr(pWal
)->mxFrame
){
1752 i64 szDb
= pWal
->hdr
.nPage
*(i64
)szPage
;
1753 testcase( IS_BIG_INT(szDb
) );
1754 rc
= sqlite3OsTruncate(pWal
->pDbFd
, szDb
);
1755 if( rc
==SQLITE_OK
&& sync_flags
){
1756 rc
= sqlite3OsSync(pWal
->pDbFd
, sync_flags
);
1759 if( rc
==SQLITE_OK
){
1760 pInfo
->nBackfill
= mxSafeFrame
;
1764 /* Release the reader lock held while backfilling */
1765 walUnlockExclusive(pWal
, WAL_READ_LOCK(0), 1);
1768 if( rc
==SQLITE_BUSY
){
1769 /* Reset the return code so as not to report a checkpoint failure
1770 ** just because there are active readers. */
1774 /* If this is an SQLITE_CHECKPOINT_RESTART operation, and the entire wal
1775 ** file has been copied into the database file, then block until all
1776 ** readers have finished using the wal file. This ensures that the next
1777 ** process to write to the database restarts the wal file.
1779 if( rc
==SQLITE_OK
&& eMode
!=SQLITE_CHECKPOINT_PASSIVE
){
1780 assert( pWal
->writeLock
);
1781 if( pInfo
->nBackfill
<pWal
->hdr
.mxFrame
){
1783 }else if( eMode
==SQLITE_CHECKPOINT_RESTART
){
1784 assert( mxSafeFrame
==pWal
->hdr
.mxFrame
);
1785 rc
= walBusyLock(pWal
, xBusy
, pBusyArg
, WAL_READ_LOCK(1), WAL_NREADER
-1);
1786 if( rc
==SQLITE_OK
){
1787 walUnlockExclusive(pWal
, WAL_READ_LOCK(1), WAL_NREADER
-1);
1793 walIteratorFree(pIter
);
1798 ** If the WAL file is currently larger than nMax bytes in size, truncate
1799 ** it to exactly nMax bytes. If an error occurs while doing so, ignore it.
1801 static void walLimitSize(Wal
*pWal
, i64 nMax
){
1804 sqlite3BeginBenignMalloc();
1805 rx
= sqlite3OsFileSize(pWal
->pWalFd
, &sz
);
1806 if( rx
==SQLITE_OK
&& (sz
> nMax
) ){
1807 rx
= sqlite3OsTruncate(pWal
->pWalFd
, nMax
);
1809 sqlite3EndBenignMalloc();
1811 sqlite3_log(rx
, "cannot limit WAL size: %s", pWal
->zWalName
);
1816 ** Close a connection to a log file.
1818 int sqlite3WalClose(
1819 Wal
*pWal
, /* Wal to close */
1820 int sync_flags
, /* Flags to pass to OsSync() (or 0) */
1822 u8
*zBuf
/* Buffer of at least nBuf bytes */
1826 int isDelete
= 0; /* True to unlink wal and wal-index files */
1828 /* If an EXCLUSIVE lock can be obtained on the database file (using the
1829 ** ordinary, rollback-mode locking methods, this guarantees that the
1830 ** connection associated with this log file is the only connection to
1831 ** the database. In this case checkpoint the database and unlink both
1832 ** the wal and wal-index files.
1834 ** The EXCLUSIVE lock is not released before returning.
1836 rc
= sqlite3OsLock(pWal
->pDbFd
, SQLITE_LOCK_EXCLUSIVE
);
1837 if( rc
==SQLITE_OK
){
1838 if( pWal
->exclusiveMode
==WAL_NORMAL_MODE
){
1839 pWal
->exclusiveMode
= WAL_EXCLUSIVE_MODE
;
1841 rc
= sqlite3WalCheckpoint(
1842 pWal
, SQLITE_CHECKPOINT_PASSIVE
, 0, 0, sync_flags
, nBuf
, zBuf
, 0, 0
1844 if( rc
==SQLITE_OK
){
1846 sqlite3OsFileControlHint(
1847 pWal
->pDbFd
, SQLITE_FCNTL_PERSIST_WAL
, &bPersist
1850 /* Try to delete the WAL file if the checkpoint completed and
1851 ** fsyned (rc==SQLITE_OK) and if we are not in persistent-wal
1852 ** mode (!bPersist) */
1854 }else if( pWal
->mxWalSize
>=0 ){
1855 /* Try to truncate the WAL file to zero bytes if the checkpoint
1856 ** completed and fsynced (rc==SQLITE_OK) and we are in persistent
1857 ** WAL mode (bPersist) and if the PRAGMA journal_size_limit is a
1858 ** non-negative value (pWal->mxWalSize>=0). Note that we truncate
1859 ** to zero bytes as truncating to the journal_size_limit might
1860 ** leave a corrupt WAL file on disk. */
1861 walLimitSize(pWal
, 0);
1866 walIndexClose(pWal
, isDelete
);
1867 sqlite3OsClose(pWal
->pWalFd
);
1869 sqlite3BeginBenignMalloc();
1870 sqlite3OsDelete(pWal
->pVfs
, pWal
->zWalName
, 0);
1871 sqlite3EndBenignMalloc();
1873 WALTRACE(("WAL%p: closed\n", pWal
));
1874 sqlite3_free((void *)pWal
->apWiData
);
1881 ** Try to read the wal-index header. Return 0 on success and 1 if
1882 ** there is a problem.
1884 ** The wal-index is in shared memory. Another thread or process might
1885 ** be writing the header at the same time this procedure is trying to
1886 ** read it, which might result in inconsistency. A dirty read is detected
1887 ** by verifying that both copies of the header are the same and also by
1888 ** a checksum on the header.
1890 ** If and only if the read is consistent and the header is different from
1891 ** pWal->hdr, then pWal->hdr is updated to the content of the new header
1892 ** and *pChanged is set to 1.
1894 ** If the checksum cannot be verified return non-zero. If the header
1895 ** is read successfully and the checksum verified, return zero.
1897 static int walIndexTryHdr(Wal
*pWal
, int *pChanged
){
1898 u32 aCksum
[2]; /* Checksum on the header content */
1899 WalIndexHdr h1
, h2
; /* Two copies of the header content */
1900 WalIndexHdr
volatile *aHdr
; /* Header in shared memory */
1902 /* The first page of the wal-index must be mapped at this point. */
1903 assert( pWal
->nWiData
>0 && pWal
->apWiData
[0] );
1905 /* Read the header. This might happen concurrently with a write to the
1906 ** same area of shared memory on a different CPU in a SMP,
1907 ** meaning it is possible that an inconsistent snapshot is read
1908 ** from the file. If this happens, return non-zero.
1910 ** There are two copies of the header at the beginning of the wal-index.
1911 ** When reading, read [0] first then [1]. Writes are in the reverse order.
1912 ** Memory barriers are used to prevent the compiler or the hardware from
1913 ** reordering the reads and writes.
1915 aHdr
= walIndexHdr(pWal
);
1916 memcpy(&h1
, (void *)&aHdr
[0], sizeof(h1
));
1917 walShmBarrier(pWal
);
1918 memcpy(&h2
, (void *)&aHdr
[1], sizeof(h2
));
1920 if( memcmp(&h1
, &h2
, sizeof(h1
))!=0 ){
1921 return 1; /* Dirty read */
1924 return 1; /* Malformed header - probably all zeros */
1926 walChecksumBytes(1, (u8
*)&h1
, sizeof(h1
)-sizeof(h1
.aCksum
), 0, aCksum
);
1927 if( aCksum
[0]!=h1
.aCksum
[0] || aCksum
[1]!=h1
.aCksum
[1] ){
1928 return 1; /* Checksum does not match */
1931 if( memcmp(&pWal
->hdr
, &h1
, sizeof(WalIndexHdr
)) ){
1933 memcpy(&pWal
->hdr
, &h1
, sizeof(WalIndexHdr
));
1934 pWal
->szPage
= (pWal
->hdr
.szPage
&0xfe00) + ((pWal
->hdr
.szPage
&0x0001)<<16);
1935 testcase( pWal
->szPage
<=32768 );
1936 testcase( pWal
->szPage
>=65536 );
1939 /* The header was successfully read. Return zero. */
1944 ** Read the wal-index header from the wal-index and into pWal->hdr.
1945 ** If the wal-header appears to be corrupt, try to reconstruct the
1946 ** wal-index from the WAL before returning.
1948 ** Set *pChanged to 1 if the wal-index header value in pWal->hdr is
1949 ** changed by this opertion. If pWal->hdr is unchanged, set *pChanged
1952 ** If the wal-index header is successfully read, return SQLITE_OK.
1953 ** Otherwise an SQLite error code.
1955 static int walIndexReadHdr(Wal
*pWal
, int *pChanged
){
1956 int rc
; /* Return code */
1957 int badHdr
; /* True if a header read failed */
1958 volatile u32
*page0
; /* Chunk of wal-index containing header */
1960 /* Ensure that page 0 of the wal-index (the page that contains the
1961 ** wal-index header) is mapped. Return early if an error occurs here.
1964 rc
= walIndexPage(pWal
, 0, &page0
);
1965 if( rc
!=SQLITE_OK
){
1968 assert( page0
|| pWal
->writeLock
==0 );
1970 /* If the first page of the wal-index has been mapped, try to read the
1971 ** wal-index header immediately, without holding any lock. This usually
1972 ** works, but may fail if the wal-index header is corrupt or currently
1973 ** being modified by another thread or process.
1975 badHdr
= (page0
? walIndexTryHdr(pWal
, pChanged
) : 1);
1977 /* If the first attempt failed, it might have been due to a race
1978 ** with a writer. So get a WRITE lock and try again.
1980 assert( badHdr
==0 || pWal
->writeLock
==0 );
1982 if( pWal
->readOnly
& WAL_SHM_RDONLY
){
1983 if( SQLITE_OK
==(rc
= walLockShared(pWal
, WAL_WRITE_LOCK
)) ){
1984 walUnlockShared(pWal
, WAL_WRITE_LOCK
);
1985 rc
= SQLITE_READONLY_RECOVERY
;
1987 }else if( SQLITE_OK
==(rc
= walLockExclusive(pWal
, WAL_WRITE_LOCK
, 1)) ){
1988 pWal
->writeLock
= 1;
1989 if( SQLITE_OK
==(rc
= walIndexPage(pWal
, 0, &page0
)) ){
1990 badHdr
= walIndexTryHdr(pWal
, pChanged
);
1992 /* If the wal-index header is still malformed even while holding
1993 ** a WRITE lock, it can only mean that the header is corrupted and
1994 ** needs to be reconstructed. So run recovery to do exactly that.
1996 rc
= walIndexRecover(pWal
);
2000 pWal
->writeLock
= 0;
2001 walUnlockExclusive(pWal
, WAL_WRITE_LOCK
, 1);
2005 /* If the header is read successfully, check the version number to make
2006 ** sure the wal-index was not constructed with some future format that
2007 ** this version of SQLite cannot understand.
2009 if( badHdr
==0 && pWal
->hdr
.iVersion
!=WALINDEX_MAX_VERSION
){
2010 rc
= SQLITE_CANTOPEN_BKPT
;
2017 ** This is the value that walTryBeginRead returns when it needs to
2020 #define WAL_RETRY (-1)
2023 ** Attempt to start a read transaction. This might fail due to a race or
2024 ** other transient condition. When that happens, it returns WAL_RETRY to
2025 ** indicate to the caller that it is safe to retry immediately.
2027 ** On success return SQLITE_OK. On a permanent failure (such an
2028 ** I/O error or an SQLITE_BUSY because another process is running
2029 ** recovery) return a positive error code.
2031 ** The useWal parameter is true to force the use of the WAL and disable
2032 ** the case where the WAL is bypassed because it has been completely
2033 ** checkpointed. If useWal==0 then this routine calls walIndexReadHdr()
2034 ** to make a copy of the wal-index header into pWal->hdr. If the
2035 ** wal-index header has changed, *pChanged is set to 1 (as an indication
2036 ** to the caller that the local paget cache is obsolete and needs to be
2037 ** flushed.) When useWal==1, the wal-index header is assumed to already
2038 ** be loaded and the pChanged parameter is unused.
2040 ** The caller must set the cnt parameter to the number of prior calls to
2041 ** this routine during the current read attempt that returned WAL_RETRY.
2042 ** This routine will start taking more aggressive measures to clear the
2043 ** race conditions after multiple WAL_RETRY returns, and after an excessive
2044 ** number of errors will ultimately return SQLITE_PROTOCOL. The
2045 ** SQLITE_PROTOCOL return indicates that some other process has gone rogue
2046 ** and is not honoring the locking protocol. There is a vanishingly small
2047 ** chance that SQLITE_PROTOCOL could be returned because of a run of really
2048 ** bad luck when there is lots of contention for the wal-index, but that
2049 ** possibility is so small that it can be safely neglected, we believe.
2051 ** On success, this routine obtains a read lock on
2052 ** WAL_READ_LOCK(pWal->readLock). The pWal->readLock integer is
2053 ** in the range 0 <= pWal->readLock < WAL_NREADER. If pWal->readLock==(-1)
2054 ** that means the Wal does not hold any read lock. The reader must not
2055 ** access any database page that is modified by a WAL frame up to and
2056 ** including frame number aReadMark[pWal->readLock]. The reader will
2057 ** use WAL frames up to and including pWal->hdr.mxFrame if pWal->readLock>0
2058 ** Or if pWal->readLock==0, then the reader will ignore the WAL
2059 ** completely and get all content directly from the database file.
2060 ** If the useWal parameter is 1 then the WAL will never be ignored and
2061 ** this routine will always set pWal->readLock>0 on success.
2062 ** When the read transaction is completed, the caller must release the
2063 ** lock on WAL_READ_LOCK(pWal->readLock) and set pWal->readLock to -1.
2065 ** This routine uses the nBackfill and aReadMark[] fields of the header
2066 ** to select a particular WAL_READ_LOCK() that strives to let the
2067 ** checkpoint process do as much work as possible. This routine might
2068 ** update values of the aReadMark[] array in the header, but if it does
2069 ** so it takes care to hold an exclusive lock on the corresponding
2070 ** WAL_READ_LOCK() while changing values.
2072 static int walTryBeginRead(Wal
*pWal
, int *pChanged
, int useWal
, int cnt
){
2073 volatile WalCkptInfo
*pInfo
; /* Checkpoint information in wal-index */
2074 u32 mxReadMark
; /* Largest aReadMark[] value */
2075 int mxI
; /* Index of largest aReadMark[] value */
2076 int i
; /* Loop counter */
2077 int rc
= SQLITE_OK
; /* Return code */
2079 assert( pWal
->readLock
<0 ); /* Not currently locked */
2081 /* Take steps to avoid spinning forever if there is a protocol error.
2083 ** Circumstances that cause a RETRY should only last for the briefest
2084 ** instances of time. No I/O or other system calls are done while the
2085 ** locks are held, so the locks should not be held for very long. But
2086 ** if we are unlucky, another process that is holding a lock might get
2087 ** paged out or take a page-fault that is time-consuming to resolve,
2088 ** during the few nanoseconds that it is holding the lock. In that case,
2089 ** it might take longer than normal for the lock to free.
2091 ** After 5 RETRYs, we begin calling sqlite3OsSleep(). The first few
2092 ** calls to sqlite3OsSleep() have a delay of 1 microsecond. Really this
2093 ** is more of a scheduler yield than an actual delay. But on the 10th
2094 ** an subsequent retries, the delays start becoming longer and longer,
2095 ** so that on the 100th (and last) RETRY we delay for 21 milliseconds.
2096 ** The total delay time before giving up is less than 1 second.
2099 int nDelay
= 1; /* Pause time in microseconds */
2101 VVA_ONLY( pWal
->lockError
= 1; )
2102 return SQLITE_PROTOCOL
;
2104 if( cnt
>=10 ) nDelay
= (cnt
-9)*238; /* Max delay 21ms. Total delay 996ms */
2105 sqlite3OsSleep(pWal
->pVfs
, nDelay
);
2109 rc
= walIndexReadHdr(pWal
, pChanged
);
2110 if( rc
==SQLITE_BUSY
){
2111 /* If there is not a recovery running in another thread or process
2112 ** then convert BUSY errors to WAL_RETRY. If recovery is known to
2113 ** be running, convert BUSY to BUSY_RECOVERY. There is a race here
2114 ** which might cause WAL_RETRY to be returned even if BUSY_RECOVERY
2115 ** would be technically correct. But the race is benign since with
2116 ** WAL_RETRY this routine will be called again and will probably be
2117 ** right on the second iteration.
2119 if( pWal
->apWiData
[0]==0 ){
2120 /* This branch is taken when the xShmMap() method returns SQLITE_BUSY.
2121 ** We assume this is a transient condition, so return WAL_RETRY. The
2122 ** xShmMap() implementation used by the default unix and win32 VFS
2123 ** modules may return SQLITE_BUSY due to a race condition in the
2124 ** code that determines whether or not the shared-memory region
2125 ** must be zeroed before the requested page is returned.
2128 }else if( SQLITE_OK
==(rc
= walLockShared(pWal
, WAL_RECOVER_LOCK
)) ){
2129 walUnlockShared(pWal
, WAL_RECOVER_LOCK
);
2131 }else if( rc
==SQLITE_BUSY
){
2132 rc
= SQLITE_BUSY_RECOVERY
;
2135 if( rc
!=SQLITE_OK
){
2140 pInfo
= walCkptInfo(pWal
);
2141 if( !useWal
&& pInfo
->nBackfill
==pWal
->hdr
.mxFrame
){
2142 /* The WAL has been completely backfilled (or it is empty).
2143 ** and can be safely ignored.
2145 rc
= walLockShared(pWal
, WAL_READ_LOCK(0));
2146 walShmBarrier(pWal
);
2147 if( rc
==SQLITE_OK
){
2148 if( memcmp((void *)walIndexHdr(pWal
), &pWal
->hdr
, sizeof(WalIndexHdr
)) ){
2149 /* It is not safe to allow the reader to continue here if frames
2150 ** may have been appended to the log before READ_LOCK(0) was obtained.
2151 ** When holding READ_LOCK(0), the reader ignores the entire log file,
2152 ** which implies that the database file contains a trustworthy
2153 ** snapshoT. Since holding READ_LOCK(0) prevents a checkpoint from
2154 ** happening, this is usually correct.
2156 ** However, if frames have been appended to the log (or if the log
2157 ** is wrapped and written for that matter) before the READ_LOCK(0)
2158 ** is obtained, that is not necessarily true. A checkpointer may
2159 ** have started to backfill the appended frames but crashed before
2160 ** it finished. Leaving a corrupt image in the database file.
2162 walUnlockShared(pWal
, WAL_READ_LOCK(0));
2167 }else if( rc
!=SQLITE_BUSY
){
2172 /* If we get this far, it means that the reader will want to use
2173 ** the WAL to get at content from recent commits. The job now is
2174 ** to select one of the aReadMark[] entries that is closest to
2175 ** but not exceeding pWal->hdr.mxFrame and lock that entry.
2179 for(i
=1; i
<WAL_NREADER
; i
++){
2180 u32 thisMark
= pInfo
->aReadMark
[i
];
2181 if( mxReadMark
<=thisMark
&& thisMark
<=pWal
->hdr
.mxFrame
){
2182 assert( thisMark
!=READMARK_NOT_USED
);
2183 mxReadMark
= thisMark
;
2187 /* There was once an "if" here. The extra "{" is to preserve indentation. */
2189 if( (pWal
->readOnly
& WAL_SHM_RDONLY
)==0
2190 && (mxReadMark
<pWal
->hdr
.mxFrame
|| mxI
==0)
2192 for(i
=1; i
<WAL_NREADER
; i
++){
2193 rc
= walLockExclusive(pWal
, WAL_READ_LOCK(i
), 1);
2194 if( rc
==SQLITE_OK
){
2195 mxReadMark
= pInfo
->aReadMark
[i
] = pWal
->hdr
.mxFrame
;
2197 walUnlockExclusive(pWal
, WAL_READ_LOCK(i
), 1);
2199 }else if( rc
!=SQLITE_BUSY
){
2205 assert( rc
==SQLITE_BUSY
|| (pWal
->readOnly
& WAL_SHM_RDONLY
)!=0 );
2206 return rc
==SQLITE_BUSY
? WAL_RETRY
: SQLITE_READONLY_CANTLOCK
;
2209 rc
= walLockShared(pWal
, WAL_READ_LOCK(mxI
));
2211 return rc
==SQLITE_BUSY
? WAL_RETRY
: rc
;
2213 /* Now that the read-lock has been obtained, check that neither the
2214 ** value in the aReadMark[] array or the contents of the wal-index
2215 ** header have changed.
2217 ** It is necessary to check that the wal-index header did not change
2218 ** between the time it was read and when the shared-lock was obtained
2219 ** on WAL_READ_LOCK(mxI) was obtained to account for the possibility
2220 ** that the log file may have been wrapped by a writer, or that frames
2221 ** that occur later in the log than pWal->hdr.mxFrame may have been
2222 ** copied into the database by a checkpointer. If either of these things
2223 ** happened, then reading the database with the current value of
2224 ** pWal->hdr.mxFrame risks reading a corrupted snapshot. So, retry
2227 ** This does not guarantee that the copy of the wal-index header is up to
2228 ** date before proceeding. That would not be possible without somehow
2229 ** blocking writers. It only guarantees that a dangerous checkpoint or
2230 ** log-wrap (either of which would require an exclusive lock on
2231 ** WAL_READ_LOCK(mxI)) has not occurred since the snapshot was valid.
2233 walShmBarrier(pWal
);
2234 if( pInfo
->aReadMark
[mxI
]!=mxReadMark
2235 || memcmp((void *)walIndexHdr(pWal
), &pWal
->hdr
, sizeof(WalIndexHdr
))
2237 walUnlockShared(pWal
, WAL_READ_LOCK(mxI
));
2240 assert( mxReadMark
<=pWal
->hdr
.mxFrame
);
2241 pWal
->readLock
= (i16
)mxI
;
2248 ** Begin a read transaction on the database.
2250 ** This routine used to be called sqlite3OpenSnapshot() and with good reason:
2251 ** it takes a snapshot of the state of the WAL and wal-index for the current
2252 ** instant in time. The current thread will continue to use this snapshot.
2253 ** Other threads might append new content to the WAL and wal-index but
2254 ** that extra content is ignored by the current thread.
2256 ** If the database contents have changes since the previous read
2257 ** transaction, then *pChanged is set to 1 before returning. The
2258 ** Pager layer will use this to know that is cache is stale and
2259 ** needs to be flushed.
2261 int sqlite3WalBeginReadTransaction(Wal
*pWal
, int *pChanged
){
2262 int rc
; /* Return code */
2263 int cnt
= 0; /* Number of TryBeginRead attempts */
2266 rc
= walTryBeginRead(pWal
, pChanged
, 0, ++cnt
);
2267 }while( rc
==WAL_RETRY
);
2268 testcase( (rc
&0xff)==SQLITE_BUSY
);
2269 testcase( (rc
&0xff)==SQLITE_IOERR
);
2270 testcase( rc
==SQLITE_PROTOCOL
);
2271 testcase( rc
==SQLITE_OK
);
2276 ** Finish with a read transaction. All this does is release the
2279 void sqlite3WalEndReadTransaction(Wal
*pWal
){
2280 sqlite3WalEndWriteTransaction(pWal
);
2281 if( pWal
->readLock
>=0 ){
2282 walUnlockShared(pWal
, WAL_READ_LOCK(pWal
->readLock
));
2283 pWal
->readLock
= -1;
2288 ** Read a page from the WAL, if it is present in the WAL and if the
2289 ** current read transaction is configured to use the WAL.
2291 ** The *pInWal is set to 1 if the requested page is in the WAL and
2292 ** has been loaded. Or *pInWal is set to 0 if the page was not in
2293 ** the WAL and needs to be read out of the database.
2296 Wal
*pWal
, /* WAL handle */
2297 Pgno pgno
, /* Database page number to read data for */
2298 int *pInWal
, /* OUT: True if data is read from WAL */
2299 int nOut
, /* Size of buffer pOut in bytes */
2300 u8
*pOut
/* Buffer to write page data to */
2302 u32 iRead
= 0; /* If !=0, WAL frame to return data from */
2303 u32 iLast
= pWal
->hdr
.mxFrame
; /* Last page in WAL for this reader */
2304 int iHash
; /* Used to loop through N hash tables */
2306 /* This routine is only be called from within a read transaction. */
2307 assert( pWal
->readLock
>=0 || pWal
->lockError
);
2309 /* If the "last page" field of the wal-index header snapshot is 0, then
2310 ** no data will be read from the wal under any circumstances. Return early
2311 ** in this case as an optimization. Likewise, if pWal->readLock==0,
2312 ** then the WAL is ignored by the reader so return early, as if the
2315 if( iLast
==0 || pWal
->readLock
==0 ){
2320 /* Search the hash table or tables for an entry matching page number
2321 ** pgno. Each iteration of the following for() loop searches one
2322 ** hash table (each hash table indexes up to HASHTABLE_NPAGE frames).
2324 ** This code might run concurrently to the code in walIndexAppend()
2325 ** that adds entries to the wal-index (and possibly to this hash
2326 ** table). This means the value just read from the hash
2327 ** slot (aHash[iKey]) may have been added before or after the
2328 ** current read transaction was opened. Values added after the
2329 ** read transaction was opened may have been written incorrectly -
2330 ** i.e. these slots may contain garbage data. However, we assume
2331 ** that any slots written before the current read transaction was
2332 ** opened remain unmodified.
2334 ** For the reasons above, the if(...) condition featured in the inner
2335 ** loop of the following block is more stringent that would be required
2336 ** if we had exclusive access to the hash-table:
2338 ** (aPgno[iFrame]==pgno):
2339 ** This condition filters out normal hash-table collisions.
2342 ** This condition filters out entries that were added to the hash
2343 ** table after the current read-transaction had started.
2345 for(iHash
=walFramePage(iLast
); iHash
>=0 && iRead
==0; iHash
--){
2346 volatile ht_slot
*aHash
; /* Pointer to hash table */
2347 volatile u32
*aPgno
; /* Pointer to array of page numbers */
2348 u32 iZero
; /* Frame number corresponding to aPgno[0] */
2349 int iKey
; /* Hash slot index */
2350 int nCollide
; /* Number of hash collisions remaining */
2351 int rc
; /* Error code */
2353 rc
= walHashGet(pWal
, iHash
, &aHash
, &aPgno
, &iZero
);
2354 if( rc
!=SQLITE_OK
){
2357 nCollide
= HASHTABLE_NSLOT
;
2358 for(iKey
=walHash(pgno
); aHash
[iKey
]; iKey
=walNextHash(iKey
)){
2359 u32 iFrame
= aHash
[iKey
] + iZero
;
2360 if( iFrame
<=iLast
&& aPgno
[aHash
[iKey
]]==pgno
){
2361 /* assert( iFrame>iRead ); -- not true if there is corruption */
2364 if( (nCollide
--)==0 ){
2365 return SQLITE_CORRUPT_BKPT
;
2370 #ifdef SQLITE_ENABLE_EXPENSIVE_ASSERT
2371 /* If expensive assert() statements are available, do a linear search
2372 ** of the wal-index file content. Make sure the results agree with the
2373 ** result obtained using the hash indexes above. */
2377 for(iTest
=iLast
; iTest
>0; iTest
--){
2378 if( walFramePgno(pWal
, iTest
)==pgno
){
2383 assert( iRead
==iRead2
);
2387 /* If iRead is non-zero, then it is the log frame number that contains the
2388 ** required page. Read and return data from the log file.
2393 sz
= pWal
->hdr
.szPage
;
2394 sz
= (sz
&0xfe00) + ((sz
&0x0001)<<16);
2395 testcase( sz
<=32768 );
2396 testcase( sz
>=65536 );
2397 iOffset
= walFrameOffset(iRead
, sz
) + WAL_FRAME_HDRSIZE
;
2399 /* testcase( IS_BIG_INT(iOffset) ); // requires a 4GiB WAL */
2400 return sqlite3OsRead(pWal
->pWalFd
, pOut
, (nOut
>sz
? sz
: nOut
), iOffset
);
2409 ** Return the size of the database in pages (or zero, if unknown).
2411 Pgno
sqlite3WalDbsize(Wal
*pWal
){
2412 if( pWal
&& ALWAYS(pWal
->readLock
>=0) ){
2413 return pWal
->hdr
.nPage
;
2420 ** This function starts a write transaction on the WAL.
2422 ** A read transaction must have already been started by a prior call
2423 ** to sqlite3WalBeginReadTransaction().
2425 ** If another thread or process has written into the database since
2426 ** the read transaction was started, then it is not possible for this
2427 ** thread to write as doing so would cause a fork. So this routine
2428 ** returns SQLITE_BUSY in that case and no write transaction is started.
2430 ** There can only be a single writer active at a time.
2432 int sqlite3WalBeginWriteTransaction(Wal
*pWal
){
2435 /* Cannot start a write transaction without first holding a read
2437 assert( pWal
->readLock
>=0 );
2439 if( pWal
->readOnly
){
2440 return SQLITE_READONLY
;
2443 /* Only one writer allowed at a time. Get the write lock. Return
2444 ** SQLITE_BUSY if unable.
2446 rc
= walLockExclusive(pWal
, WAL_WRITE_LOCK
, 1);
2450 pWal
->writeLock
= 1;
2452 /* If another connection has written to the database file since the
2453 ** time the read transaction on this connection was started, then
2454 ** the write is disallowed.
2456 if( memcmp(&pWal
->hdr
, (void *)walIndexHdr(pWal
), sizeof(WalIndexHdr
))!=0 ){
2457 walUnlockExclusive(pWal
, WAL_WRITE_LOCK
, 1);
2458 pWal
->writeLock
= 0;
2466 ** End a write transaction. The commit has already been done. This
2467 ** routine merely releases the lock.
2469 int sqlite3WalEndWriteTransaction(Wal
*pWal
){
2470 if( pWal
->writeLock
){
2471 walUnlockExclusive(pWal
, WAL_WRITE_LOCK
, 1);
2472 pWal
->writeLock
= 0;
2473 pWal
->truncateOnCommit
= 0;
2479 ** If any data has been written (but not committed) to the log file, this
2480 ** function moves the write-pointer back to the start of the transaction.
2482 ** Additionally, the callback function is invoked for each frame written
2483 ** to the WAL since the start of the transaction. If the callback returns
2484 ** other than SQLITE_OK, it is not invoked again and the error code is
2485 ** returned to the caller.
2487 ** Otherwise, if the callback function does not return an error, this
2488 ** function returns SQLITE_OK.
2490 int sqlite3WalUndo(Wal
*pWal
, int (*xUndo
)(void *, Pgno
), void *pUndoCtx
){
2492 if( ALWAYS(pWal
->writeLock
) ){
2493 Pgno iMax
= pWal
->hdr
.mxFrame
;
2496 /* Restore the clients cache of the wal-index header to the state it
2497 ** was in before the client began writing to the database.
2499 memcpy(&pWal
->hdr
, (void *)walIndexHdr(pWal
), sizeof(WalIndexHdr
));
2501 for(iFrame
=pWal
->hdr
.mxFrame
+1;
2502 ALWAYS(rc
==SQLITE_OK
) && iFrame
<=iMax
;
2505 /* This call cannot fail. Unless the page for which the page number
2506 ** is passed as the second argument is (a) in the cache and
2507 ** (b) has an outstanding reference, then xUndo is either a no-op
2508 ** (if (a) is false) or simply expels the page from the cache (if (b)
2511 ** If the upper layer is doing a rollback, it is guaranteed that there
2512 ** are no outstanding references to any page other than page 1. And
2513 ** page 1 is never written to the log until the transaction is
2514 ** committed. As a result, the call to xUndo may not fail.
2516 assert( walFramePgno(pWal
, iFrame
)!=1 );
2517 rc
= xUndo(pUndoCtx
, walFramePgno(pWal
, iFrame
));
2519 walCleanupHash(pWal
);
2521 assert( rc
==SQLITE_OK
);
2526 ** Argument aWalData must point to an array of WAL_SAVEPOINT_NDATA u32
2527 ** values. This function populates the array with values required to
2528 ** "rollback" the write position of the WAL handle back to the current
2529 ** point in the event of a savepoint rollback (via WalSavepointUndo()).
2531 void sqlite3WalSavepoint(Wal
*pWal
, u32
*aWalData
){
2532 assert( pWal
->writeLock
);
2533 aWalData
[0] = pWal
->hdr
.mxFrame
;
2534 aWalData
[1] = pWal
->hdr
.aFrameCksum
[0];
2535 aWalData
[2] = pWal
->hdr
.aFrameCksum
[1];
2536 aWalData
[3] = pWal
->nCkpt
;
2540 ** Move the write position of the WAL back to the point identified by
2541 ** the values in the aWalData[] array. aWalData must point to an array
2542 ** of WAL_SAVEPOINT_NDATA u32 values that has been previously populated
2543 ** by a call to WalSavepoint().
2545 int sqlite3WalSavepointUndo(Wal
*pWal
, u32
*aWalData
){
2548 assert( pWal
->writeLock
);
2549 assert( aWalData
[3]!=pWal
->nCkpt
|| aWalData
[0]<=pWal
->hdr
.mxFrame
);
2551 if( aWalData
[3]!=pWal
->nCkpt
){
2552 /* This savepoint was opened immediately after the write-transaction
2553 ** was started. Right after that, the writer decided to wrap around
2554 ** to the start of the log. Update the savepoint values to match.
2557 aWalData
[3] = pWal
->nCkpt
;
2560 if( aWalData
[0]<pWal
->hdr
.mxFrame
){
2561 pWal
->hdr
.mxFrame
= aWalData
[0];
2562 pWal
->hdr
.aFrameCksum
[0] = aWalData
[1];
2563 pWal
->hdr
.aFrameCksum
[1] = aWalData
[2];
2564 walCleanupHash(pWal
);
2572 ** This function is called just before writing a set of frames to the log
2573 ** file (see sqlite3WalFrames()). It checks to see if, instead of appending
2574 ** to the current log file, it is possible to overwrite the start of the
2575 ** existing log file with the new frames (i.e. "reset" the log). If so,
2576 ** it sets pWal->hdr.mxFrame to 0. Otherwise, pWal->hdr.mxFrame is left
2579 ** SQLITE_OK is returned if no error is encountered (regardless of whether
2580 ** or not pWal->hdr.mxFrame is modified). An SQLite error code is returned
2581 ** if an error occurs.
2583 static int walRestartLog(Wal
*pWal
){
2587 if( pWal
->readLock
==0 ){
2588 volatile WalCkptInfo
*pInfo
= walCkptInfo(pWal
);
2589 assert( pInfo
->nBackfill
==pWal
->hdr
.mxFrame
);
2590 if( pInfo
->nBackfill
>0 ){
2592 sqlite3_randomness(4, &salt1
);
2593 rc
= walLockExclusive(pWal
, WAL_READ_LOCK(1), WAL_NREADER
-1);
2594 if( rc
==SQLITE_OK
){
2595 /* If all readers are using WAL_READ_LOCK(0) (in other words if no
2596 ** readers are currently using the WAL), then the transactions
2597 ** frames will overwrite the start of the existing log. Update the
2598 ** wal-index header to reflect this.
2600 ** In theory it would be Ok to update the cache of the header only
2601 ** at this point. But updating the actual wal-index header is also
2602 ** safe and means there is no special case for sqlite3WalUndo()
2603 ** to handle if this transaction is rolled back.
2605 int i
; /* Loop counter */
2606 u32
*aSalt
= pWal
->hdr
.aSalt
; /* Big-endian salt values */
2609 pWal
->hdr
.mxFrame
= 0;
2610 sqlite3Put4byte((u8
*)&aSalt
[0], 1 + sqlite3Get4byte((u8
*)&aSalt
[0]));
2612 walIndexWriteHdr(pWal
);
2613 pInfo
->nBackfill
= 0;
2614 for(i
=1; i
<WAL_NREADER
; i
++) pInfo
->aReadMark
[i
] = READMARK_NOT_USED
;
2615 assert( pInfo
->aReadMark
[0]==0 );
2616 walUnlockExclusive(pWal
, WAL_READ_LOCK(1), WAL_NREADER
-1);
2617 }else if( rc
!=SQLITE_BUSY
){
2621 walUnlockShared(pWal
, WAL_READ_LOCK(0));
2622 pWal
->readLock
= -1;
2626 rc
= walTryBeginRead(pWal
, ¬Used
, 1, ++cnt
);
2627 }while( rc
==WAL_RETRY
);
2628 assert( (rc
&0xff)!=SQLITE_BUSY
); /* BUSY not possible when useWal==1 */
2629 testcase( (rc
&0xff)==SQLITE_IOERR
);
2630 testcase( rc
==SQLITE_PROTOCOL
);
2631 testcase( rc
==SQLITE_OK
);
2637 ** Information about the current state of the WAL file and where
2638 ** the next fsync should occur - passed from sqlite3WalFrames() into
2641 typedef struct WalWriter
{
2642 Wal
*pWal
; /* The complete WAL information */
2643 sqlite3_file
*pFd
; /* The WAL file to which we write */
2644 sqlite3_int64 iSyncPoint
; /* Fsync at this offset */
2645 int syncFlags
; /* Flags for the fsync */
2646 int szPage
; /* Size of one page */
2650 ** Write iAmt bytes of content into the WAL file beginning at iOffset.
2651 ** Do a sync when crossing the p->iSyncPoint boundary.
2653 ** In other words, if iSyncPoint is in between iOffset and iOffset+iAmt,
2654 ** first write the part before iSyncPoint, then sync, then write the
2657 static int walWriteToLog(
2658 WalWriter
*p
, /* WAL to write to */
2659 void *pContent
, /* Content to be written */
2660 int iAmt
, /* Number of bytes to write */
2661 sqlite3_int64 iOffset
/* Start writing at this offset */
2664 if( iOffset
<p
->iSyncPoint
&& iOffset
+iAmt
>=p
->iSyncPoint
){
2665 int iFirstAmt
= (int)(p
->iSyncPoint
- iOffset
);
2666 rc
= sqlite3OsWrite(p
->pFd
, pContent
, iFirstAmt
, iOffset
);
2668 iOffset
+= iFirstAmt
;
2670 pContent
= (void*)(iFirstAmt
+ (char*)pContent
);
2671 assert( p
->syncFlags
& (SQLITE_SYNC_NORMAL
|SQLITE_SYNC_FULL
) );
2672 rc
= sqlite3OsSync(p
->pFd
, p
->syncFlags
);
2673 if( iAmt
==0 || rc
) return rc
;
2675 rc
= sqlite3OsWrite(p
->pFd
, pContent
, iAmt
, iOffset
);
2680 ** Write out a single frame of the WAL
2682 static int walWriteOneFrame(
2683 WalWriter
*p
, /* Where to write the frame */
2684 PgHdr
*pPage
, /* The page of the frame to be written */
2685 int nTruncate
, /* The commit flag. Usually 0. >0 for commit */
2686 sqlite3_int64 iOffset
/* Byte offset at which to write */
2688 int rc
; /* Result code from subfunctions */
2689 void *pData
; /* Data actually written */
2690 u8 aFrame
[WAL_FRAME_HDRSIZE
]; /* Buffer to assemble frame-header in */
2691 #if defined(SQLITE_HAS_CODEC)
2692 if( (pData
= sqlite3PagerCodec(pPage
))==0 ) return SQLITE_NOMEM
;
2694 pData
= pPage
->pData
;
2696 walEncodeFrame(p
->pWal
, pPage
->pgno
, nTruncate
, pData
, aFrame
);
2697 rc
= walWriteToLog(p
, aFrame
, sizeof(aFrame
), iOffset
);
2699 /* Write the page data */
2700 rc
= walWriteToLog(p
, pData
, p
->szPage
, iOffset
+sizeof(aFrame
));
2705 ** Write a set of frames to the log. The caller must hold the write-lock
2706 ** on the log file (obtained using sqlite3WalBeginWriteTransaction()).
2708 int sqlite3WalFrames(
2709 Wal
*pWal
, /* Wal handle to write to */
2710 int szPage
, /* Database page-size in bytes */
2711 PgHdr
*pList
, /* List of dirty pages to write */
2712 Pgno nTruncate
, /* Database size after this commit */
2713 int isCommit
, /* True if this is a commit */
2714 int sync_flags
/* Flags to pass to OsSync() (or 0) */
2716 int rc
; /* Used to catch return codes */
2717 u32 iFrame
; /* Next frame address */
2718 PgHdr
*p
; /* Iterator to run through pList with. */
2719 PgHdr
*pLast
= 0; /* Last frame in list */
2720 int nExtra
= 0; /* Number of extra copies of last page */
2721 int szFrame
; /* The size of a single frame */
2722 i64 iOffset
; /* Next byte to write in WAL file */
2723 WalWriter w
; /* The writer */
2726 assert( pWal
->writeLock
);
2728 /* If this frame set completes a transaction, then nTruncate>0. If
2729 ** nTruncate==0 then this frame set does not complete the transaction. */
2730 assert( (isCommit
!=0)==(nTruncate
!=0) );
2732 #if defined(SQLITE_TEST) && defined(SQLITE_DEBUG)
2733 { int cnt
; for(cnt
=0, p
=pList
; p
; p
=p
->pDirty
, cnt
++){}
2734 WALTRACE(("WAL%p: frame write begin. %d frames. mxFrame=%d. %s\n",
2735 pWal
, cnt
, pWal
->hdr
.mxFrame
, isCommit
? "Commit" : "Spill"));
2739 /* See if it is possible to write these frames into the start of the
2740 ** log file, instead of appending to it at pWal->hdr.mxFrame.
2742 if( SQLITE_OK
!=(rc
= walRestartLog(pWal
)) ){
2746 /* If this is the first frame written into the log, write the WAL
2747 ** header to the start of the WAL file. See comments at the top of
2748 ** this source file for a description of the WAL header format.
2750 iFrame
= pWal
->hdr
.mxFrame
;
2752 u8 aWalHdr
[WAL_HDRSIZE
]; /* Buffer to assemble wal-header in */
2753 u32 aCksum
[2]; /* Checksum for wal-header */
2755 sqlite3Put4byte(&aWalHdr
[0], (WAL_MAGIC
| SQLITE_BIGENDIAN
));
2756 sqlite3Put4byte(&aWalHdr
[4], WAL_MAX_VERSION
);
2757 sqlite3Put4byte(&aWalHdr
[8], szPage
);
2758 sqlite3Put4byte(&aWalHdr
[12], pWal
->nCkpt
);
2759 if( pWal
->nCkpt
==0 ) sqlite3_randomness(8, pWal
->hdr
.aSalt
);
2760 memcpy(&aWalHdr
[16], pWal
->hdr
.aSalt
, 8);
2761 walChecksumBytes(1, aWalHdr
, WAL_HDRSIZE
-2*4, 0, aCksum
);
2762 sqlite3Put4byte(&aWalHdr
[24], aCksum
[0]);
2763 sqlite3Put4byte(&aWalHdr
[28], aCksum
[1]);
2765 pWal
->szPage
= szPage
;
2766 pWal
->hdr
.bigEndCksum
= SQLITE_BIGENDIAN
;
2767 pWal
->hdr
.aFrameCksum
[0] = aCksum
[0];
2768 pWal
->hdr
.aFrameCksum
[1] = aCksum
[1];
2769 pWal
->truncateOnCommit
= 1;
2771 rc
= sqlite3OsWrite(pWal
->pWalFd
, aWalHdr
, sizeof(aWalHdr
), 0);
2772 WALTRACE(("WAL%p: wal-header write %s\n", pWal
, rc
? "failed" : "ok"));
2773 if( rc
!=SQLITE_OK
){
2777 /* Sync the header (unless SQLITE_IOCAP_SEQUENTIAL is true or unless
2778 ** all syncing is turned off by PRAGMA synchronous=OFF). Otherwise
2779 ** an out-of-order write following a WAL restart could result in
2780 ** database corruption. See the ticket:
2782 ** http://localhost:591/sqlite/info/ff5be73dee
2784 if( pWal
->syncHeader
&& sync_flags
){
2785 rc
= sqlite3OsSync(pWal
->pWalFd
, sync_flags
& SQLITE_SYNC_MASK
);
2789 assert( (int)pWal
->szPage
==szPage
);
2791 /* Setup information needed to write frames into the WAL */
2793 w
.pFd
= pWal
->pWalFd
;
2795 w
.syncFlags
= sync_flags
;
2797 iOffset
= walFrameOffset(iFrame
+1, szPage
);
2798 szFrame
= szPage
+ WAL_FRAME_HDRSIZE
;
2800 /* Write all frames into the log file exactly once */
2801 for(p
=pList
; p
; p
=p
->pDirty
){
2802 int nDbSize
; /* 0 normally. Positive == commit flag */
2804 assert( iOffset
==walFrameOffset(iFrame
, szPage
) );
2805 nDbSize
= (isCommit
&& p
->pDirty
==0) ? nTruncate
: 0;
2806 rc
= walWriteOneFrame(&w
, p
, nDbSize
, iOffset
);
2812 /* If this is the end of a transaction, then we might need to pad
2813 ** the transaction and/or sync the WAL file.
2815 ** Padding and syncing only occur if this set of frames complete a
2816 ** transaction and if PRAGMA synchronous=FULL. If synchronous==NORMAL
2817 ** or synchonous==OFF, then no padding or syncing are needed.
2819 ** If SQLITE_IOCAP_POWERSAFE_OVERWRITE is defined, then padding is not
2820 ** needed and only the sync is done. If padding is needed, then the
2821 ** final frame is repeated (with its commit mark) until the next sector
2822 ** boundary is crossed. Only the part of the WAL prior to the last
2823 ** sector boundary is synced; the part of the last frame that extends
2824 ** past the sector boundary is written after the sync.
2826 if( isCommit
&& (sync_flags
& WAL_SYNC_TRANSACTIONS
)!=0 ){
2827 if( pWal
->padToSectorBoundary
){
2828 int sectorSize
= sqlite3OsSectorSize(pWal
->pWalFd
);
2829 w
.iSyncPoint
= ((iOffset
+sectorSize
-1)/sectorSize
)*sectorSize
;
2830 while( iOffset
<w
.iSyncPoint
){
2831 rc
= walWriteOneFrame(&w
, pLast
, nTruncate
, iOffset
);
2837 rc
= sqlite3OsSync(w
.pFd
, sync_flags
& SQLITE_SYNC_MASK
);
2841 /* If this frame set completes the first transaction in the WAL and
2842 ** if PRAGMA journal_size_limit is set, then truncate the WAL to the
2843 ** journal size limit, if possible.
2845 if( isCommit
&& pWal
->truncateOnCommit
&& pWal
->mxWalSize
>=0 ){
2846 i64 sz
= pWal
->mxWalSize
;
2847 if( walFrameOffset(iFrame
+nExtra
+1, szPage
)>pWal
->mxWalSize
){
2848 sz
= walFrameOffset(iFrame
+nExtra
+1, szPage
);
2850 walLimitSize(pWal
, sz
);
2851 pWal
->truncateOnCommit
= 0;
2854 /* Append data to the wal-index. It is not necessary to lock the
2855 ** wal-index to do this as the SQLITE_SHM_WRITE lock held on the wal-index
2856 ** guarantees that there are no other writers, and no data that may
2857 ** be in use by existing readers is being overwritten.
2859 iFrame
= pWal
->hdr
.mxFrame
;
2860 for(p
=pList
; p
&& rc
==SQLITE_OK
; p
=p
->pDirty
){
2862 rc
= walIndexAppend(pWal
, iFrame
, p
->pgno
);
2864 while( rc
==SQLITE_OK
&& nExtra
>0 ){
2867 rc
= walIndexAppend(pWal
, iFrame
, pLast
->pgno
);
2870 if( rc
==SQLITE_OK
){
2871 /* Update the private copy of the header. */
2872 pWal
->hdr
.szPage
= (u16
)((szPage
&0xff00) | (szPage
>>16));
2873 testcase( szPage
<=32768 );
2874 testcase( szPage
>=65536 );
2875 pWal
->hdr
.mxFrame
= iFrame
;
2877 pWal
->hdr
.iChange
++;
2878 pWal
->hdr
.nPage
= nTruncate
;
2880 /* If this is a commit, update the wal-index header too. */
2882 walIndexWriteHdr(pWal
);
2883 pWal
->iCallback
= iFrame
;
2887 WALTRACE(("WAL%p: frame write %s\n", pWal
, rc
? "failed" : "ok"));
2892 ** This routine is called to implement sqlite3_wal_checkpoint() and
2893 ** related interfaces.
2895 ** Obtain a CHECKPOINT lock and then backfill as much information as
2896 ** we can from WAL into the database.
2898 ** If parameter xBusy is not NULL, it is a pointer to a busy-handler
2899 ** callback. In this case this function runs a blocking checkpoint.
2901 int sqlite3WalCheckpoint(
2902 Wal
*pWal
, /* Wal connection */
2903 int eMode
, /* PASSIVE, FULL or RESTART */
2904 int (*xBusy
)(void*), /* Function to call when busy */
2905 void *pBusyArg
, /* Context argument for xBusyHandler */
2906 int sync_flags
, /* Flags to sync db file with (or 0) */
2907 int nBuf
, /* Size of temporary buffer */
2908 u8
*zBuf
, /* Temporary buffer to use */
2909 int *pnLog
, /* OUT: Number of frames in WAL */
2910 int *pnCkpt
/* OUT: Number of backfilled frames in WAL */
2912 int rc
; /* Return code */
2913 int isChanged
= 0; /* True if a new wal-index header is loaded */
2914 int eMode2
= eMode
; /* Mode to pass to walCheckpoint() */
2916 assert( pWal
->ckptLock
==0 );
2917 assert( pWal
->writeLock
==0 );
2919 if( pWal
->readOnly
) return SQLITE_READONLY
;
2920 WALTRACE(("WAL%p: checkpoint begins\n", pWal
));
2921 rc
= walLockExclusive(pWal
, WAL_CKPT_LOCK
, 1);
2923 /* Usually this is SQLITE_BUSY meaning that another thread or process
2924 ** is already running a checkpoint, or maybe a recovery. But it might
2925 ** also be SQLITE_IOERR. */
2930 /* If this is a blocking-checkpoint, then obtain the write-lock as well
2931 ** to prevent any writers from running while the checkpoint is underway.
2932 ** This has to be done before the call to walIndexReadHdr() below.
2934 ** If the writer lock cannot be obtained, then a passive checkpoint is
2935 ** run instead. Since the checkpointer is not holding the writer lock,
2936 ** there is no point in blocking waiting for any readers. Assuming no
2937 ** other error occurs, this function will return SQLITE_BUSY to the caller.
2939 if( eMode
!=SQLITE_CHECKPOINT_PASSIVE
){
2940 rc
= walBusyLock(pWal
, xBusy
, pBusyArg
, WAL_WRITE_LOCK
, 1);
2941 if( rc
==SQLITE_OK
){
2942 pWal
->writeLock
= 1;
2943 }else if( rc
==SQLITE_BUSY
){
2944 eMode2
= SQLITE_CHECKPOINT_PASSIVE
;
2949 /* Read the wal-index header. */
2950 if( rc
==SQLITE_OK
){
2951 rc
= walIndexReadHdr(pWal
, &isChanged
);
2954 /* Copy data from the log to the database file. */
2955 if( rc
==SQLITE_OK
){
2956 if( pWal
->hdr
.mxFrame
&& walPagesize(pWal
)!=nBuf
){
2957 rc
= SQLITE_CORRUPT_BKPT
;
2959 rc
= walCheckpoint(pWal
, eMode2
, xBusy
, pBusyArg
, sync_flags
, zBuf
);
2962 /* If no error occurred, set the output variables. */
2963 if( rc
==SQLITE_OK
|| rc
==SQLITE_BUSY
){
2964 if( pnLog
) *pnLog
= (int)pWal
->hdr
.mxFrame
;
2965 if( pnCkpt
) *pnCkpt
= (int)(walCkptInfo(pWal
)->nBackfill
);
2970 /* If a new wal-index header was loaded before the checkpoint was
2971 ** performed, then the pager-cache associated with pWal is now
2972 ** out of date. So zero the cached wal-index header to ensure that
2973 ** next time the pager opens a snapshot on this database it knows that
2974 ** the cache needs to be reset.
2976 memset(&pWal
->hdr
, 0, sizeof(WalIndexHdr
));
2979 /* Release the locks. */
2980 sqlite3WalEndWriteTransaction(pWal
);
2981 walUnlockExclusive(pWal
, WAL_CKPT_LOCK
, 1);
2983 WALTRACE(("WAL%p: checkpoint %s\n", pWal
, rc
? "failed" : "ok"));
2984 return (rc
==SQLITE_OK
&& eMode
!=eMode2
? SQLITE_BUSY
: rc
);
2987 /* Return the value to pass to a sqlite3_wal_hook callback, the
2988 ** number of frames in the WAL at the point of the last commit since
2989 ** sqlite3WalCallback() was called. If no commits have occurred since
2990 ** the last call, then return 0.
2992 int sqlite3WalCallback(Wal
*pWal
){
2995 ret
= pWal
->iCallback
;
2996 pWal
->iCallback
= 0;
3002 ** This function is called to change the WAL subsystem into or out
3003 ** of locking_mode=EXCLUSIVE.
3005 ** If op is zero, then attempt to change from locking_mode=EXCLUSIVE
3006 ** into locking_mode=NORMAL. This means that we must acquire a lock
3007 ** on the pWal->readLock byte. If the WAL is already in locking_mode=NORMAL
3008 ** or if the acquisition of the lock fails, then return 0. If the
3009 ** transition out of exclusive-mode is successful, return 1. This
3010 ** operation must occur while the pager is still holding the exclusive
3011 ** lock on the main database file.
3013 ** If op is one, then change from locking_mode=NORMAL into
3014 ** locking_mode=EXCLUSIVE. This means that the pWal->readLock must
3015 ** be released. Return 1 if the transition is made and 0 if the
3016 ** WAL is already in exclusive-locking mode - meaning that this
3017 ** routine is a no-op. The pager must already hold the exclusive lock
3018 ** on the main database file before invoking this operation.
3020 ** If op is negative, then do a dry-run of the op==1 case but do
3021 ** not actually change anything. The pager uses this to see if it
3022 ** should acquire the database exclusive lock prior to invoking
3025 int sqlite3WalExclusiveMode(Wal
*pWal
, int op
){
3027 assert( pWal
->writeLock
==0 );
3028 assert( pWal
->exclusiveMode
!=WAL_HEAPMEMORY_MODE
|| op
==-1 );
3030 /* pWal->readLock is usually set, but might be -1 if there was a
3031 ** prior error while attempting to acquire are read-lock. This cannot
3032 ** happen if the connection is actually in exclusive mode (as no xShmLock
3033 ** locks are taken in this case). Nor should the pager attempt to
3034 ** upgrade to exclusive-mode following such an error.
3036 assert( pWal
->readLock
>=0 || pWal
->lockError
);
3037 assert( pWal
->readLock
>=0 || (op
<=0 && pWal
->exclusiveMode
==0) );
3040 if( pWal
->exclusiveMode
){
3041 pWal
->exclusiveMode
= 0;
3042 if( walLockShared(pWal
, WAL_READ_LOCK(pWal
->readLock
))!=SQLITE_OK
){
3043 pWal
->exclusiveMode
= 1;
3045 rc
= pWal
->exclusiveMode
==0;
3047 /* Already in locking_mode=NORMAL */
3051 assert( pWal
->exclusiveMode
==0 );
3052 assert( pWal
->readLock
>=0 );
3053 walUnlockShared(pWal
, WAL_READ_LOCK(pWal
->readLock
));
3054 pWal
->exclusiveMode
= 1;
3057 rc
= pWal
->exclusiveMode
==0;
3063 ** Return true if the argument is non-NULL and the WAL module is using
3064 ** heap-memory for the wal-index. Otherwise, if the argument is NULL or the
3065 ** WAL module is using shared-memory, return false.
3067 int sqlite3WalHeapMemory(Wal
*pWal
){
3068 return (pWal
&& pWal
->exclusiveMode
==WAL_HEAPMEMORY_MODE
);
3071 #ifdef SQLITE_ENABLE_ZIPVFS
3073 ** If the argument is not NULL, it points to a Wal object that holds a
3074 ** read-lock. This function returns the database page-size if it is known,
3075 ** or zero if it is not (or if pWal is NULL).
3077 int sqlite3WalFramesize(Wal
*pWal
){
3078 assert( pWal
==0 || pWal
->readLock
>=0 );
3079 return (pWal
? pWal
->szPage
: 0);
3083 #endif /* #ifndef SQLITE_OMIT_WAL */