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 code use to implement an in-memory rollback journal.
14 ** The in-memory rollback journal is used to journal transactions for
15 ** ":memory:" databases and when the journal_mode=MEMORY pragma is used.
17 ** Update: The in-memory journal is also used to temporarily cache
18 ** smaller journals that are not critical for power-loss recovery.
19 ** For example, statement journals that are not too big will be held
20 ** entirely in memory, thus reducing the number of file I/O calls, and
21 ** more importantly, reducing temporary file creation events. If these
22 ** journals become too large for memory, they are spilled to disk. But
23 ** in the common case, they are usually small and no file I/O needs to
26 #include "sqliteInt.h"
28 /* Forward references to internal structures */
29 typedef struct MemJournal MemJournal
;
30 typedef struct FilePoint FilePoint
;
31 typedef struct FileChunk FileChunk
;
34 ** The rollback journal is composed of a linked list of these structures.
36 ** The zChunk array is always at least 8 bytes in size - usually much more.
37 ** Its actual size is stored in the MemJournal.nChunkSize variable.
40 FileChunk
*pNext
; /* Next chunk in the journal */
41 u8 zChunk
[8]; /* Content of this chunk */
45 ** By default, allocate this many bytes of memory for each FileChunk object.
47 #define MEMJOURNAL_DFLT_FILECHUNKSIZE 1024
50 ** For chunk size nChunkSize, return the number of bytes that should
51 ** be allocated for each FileChunk structure.
53 #define fileChunkSize(nChunkSize) (sizeof(FileChunk) + ((nChunkSize)-8))
56 ** An instance of this object serves as a cursor into the rollback journal.
57 ** The cursor can be either for reading or writing.
60 sqlite3_int64 iOffset
; /* Offset from the beginning of the file */
61 FileChunk
*pChunk
; /* Specific chunk into which cursor points */
65 ** This structure is a subclass of sqlite3_file. Each open memory-journal
66 ** is an instance of this class.
69 const sqlite3_io_methods
*pMethod
; /* Parent class. MUST BE FIRST */
70 int nChunkSize
; /* In-memory chunk-size */
72 int nSpill
; /* Bytes of data before flushing */
73 int nSize
; /* Bytes of data currently in memory */
74 FileChunk
*pFirst
; /* Head of in-memory chunk-list */
75 FilePoint endpoint
; /* Pointer to the end of the file */
76 FilePoint readpoint
; /* Pointer to the end of the last xRead() */
78 int flags
; /* xOpen flags */
79 sqlite3_vfs
*pVfs
; /* The "real" underlying VFS */
80 const char *zJournal
; /* Name of the journal file */
84 ** Read data from the in-memory journal file. This is the implementation
85 ** of the sqlite3_vfs.xRead method.
87 static int memjrnlRead(
88 sqlite3_file
*pJfd
, /* The journal file from which to read */
89 void *zBuf
, /* Put the results here */
90 int iAmt
, /* Number of bytes to read */
91 sqlite_int64 iOfst
/* Begin reading at this offset */
93 MemJournal
*p
= (MemJournal
*)pJfd
;
99 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
100 if( (iAmt
+iOfst
)>p
->endpoint
.iOffset
){
101 return SQLITE_IOERR_SHORT_READ
;
105 assert( (iAmt
+iOfst
)<=p
->endpoint
.iOffset
);
106 assert( p
->readpoint
.iOffset
==0 || p
->readpoint
.pChunk
!=0 );
107 if( p
->readpoint
.iOffset
!=iOfst
|| iOfst
==0 ){
108 sqlite3_int64 iOff
= 0;
109 for(pChunk
=p
->pFirst
;
110 ALWAYS(pChunk
) && (iOff
+p
->nChunkSize
)<=iOfst
;
113 iOff
+= p
->nChunkSize
;
116 pChunk
= p
->readpoint
.pChunk
;
120 iChunkOffset
= (int)(iOfst
%p
->nChunkSize
);
122 int iSpace
= p
->nChunkSize
- iChunkOffset
;
123 int nCopy
= MIN(nRead
, (p
->nChunkSize
- iChunkOffset
));
124 memcpy(zOut
, (u8
*)pChunk
->zChunk
+ iChunkOffset
, nCopy
);
128 } while( nRead
>=0 && (pChunk
=pChunk
->pNext
)!=0 && nRead
>0 );
129 p
->readpoint
.iOffset
= pChunk
? iOfst
+iAmt
: 0;
130 p
->readpoint
.pChunk
= pChunk
;
136 ** Free the list of FileChunk structures headed at MemJournal.pFirst.
138 static void memjrnlFreeChunks(MemJournal
*p
){
141 for(pIter
=p
->pFirst
; pIter
; pIter
=pNext
){
142 pNext
= pIter
->pNext
;
149 ** Flush the contents of memory to a real file on disk.
151 static int memjrnlCreateFile(MemJournal
*p
){
153 sqlite3_file
*pReal
= (sqlite3_file
*)p
;
154 MemJournal copy
= *p
;
156 memset(p
, 0, sizeof(MemJournal
));
157 rc
= sqlite3OsOpen(copy
.pVfs
, copy
.zJournal
, pReal
, copy
.flags
, 0);
159 int nChunk
= copy
.nChunkSize
;
162 for(pIter
=copy
.pFirst
; pIter
; pIter
=pIter
->pNext
){
163 if( iOff
+ nChunk
> copy
.endpoint
.iOffset
){
164 nChunk
= copy
.endpoint
.iOffset
- iOff
;
166 rc
= sqlite3OsWrite(pReal
, (u8
*)pIter
->zChunk
, nChunk
, iOff
);
171 /* No error has occurred. Free the in-memory buffers. */
172 memjrnlFreeChunks(©
);
176 /* If an error occurred while creating or writing to the file, restore
177 ** the original before returning. This way, SQLite uses the in-memory
178 ** journal data to roll back changes made to the internal page-cache
179 ** before this function was called. */
180 sqlite3OsClose(pReal
);
188 ** Write data to the file.
190 static int memjrnlWrite(
191 sqlite3_file
*pJfd
, /* The journal file into which to write */
192 const void *zBuf
, /* Take data to be written from here */
193 int iAmt
, /* Number of bytes to write */
194 sqlite_int64 iOfst
/* Begin writing at this offset into the file */
196 MemJournal
*p
= (MemJournal
*)pJfd
;
198 u8
*zWrite
= (u8
*)zBuf
;
200 /* If the file should be created now, create it and write the new data
201 ** into the file on disk. */
202 if( p
->nSpill
>0 && (iAmt
+iOfst
)>p
->nSpill
){
203 int rc
= memjrnlCreateFile(p
);
205 rc
= sqlite3OsWrite(pJfd
, zBuf
, iAmt
, iOfst
);
210 /* If the contents of this write should be stored in memory */
212 /* An in-memory journal file should only ever be appended to. Random
213 ** access writes are not required. The only exception to this is when
214 ** the in-memory journal is being used by a connection using the
215 ** atomic-write optimization. In this case the first 28 bytes of the
216 ** journal file may be written as part of committing the transaction. */
217 assert( iOfst
==p
->endpoint
.iOffset
|| iOfst
==0 );
218 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
219 if( iOfst
==0 && p
->pFirst
){
220 assert( p
->nChunkSize
>iAmt
);
221 memcpy((u8
*)p
->pFirst
->zChunk
, zBuf
, iAmt
);
224 assert( iOfst
>0 || p
->pFirst
==0 );
228 FileChunk
*pChunk
= p
->endpoint
.pChunk
;
229 int iChunkOffset
= (int)(p
->endpoint
.iOffset
%p
->nChunkSize
);
230 int iSpace
= MIN(nWrite
, p
->nChunkSize
- iChunkOffset
);
232 if( iChunkOffset
==0 ){
233 /* New chunk is required to extend the file. */
234 FileChunk
*pNew
= sqlite3_malloc(fileChunkSize(p
->nChunkSize
));
236 return SQLITE_IOERR_NOMEM_BKPT
;
241 pChunk
->pNext
= pNew
;
243 assert( !p
->pFirst
);
246 p
->endpoint
.pChunk
= pNew
;
249 memcpy((u8
*)p
->endpoint
.pChunk
->zChunk
+ iChunkOffset
, zWrite
, iSpace
);
252 p
->endpoint
.iOffset
+= iSpace
;
254 p
->nSize
= iAmt
+ iOfst
;
262 ** Truncate the file.
264 ** If the journal file is already on disk, truncate it there. Or, if it
265 ** is still in main memory but is being truncated to zero bytes in size,
268 static int memjrnlTruncate(sqlite3_file
*pJfd
, sqlite_int64 size
){
269 MemJournal
*p
= (MemJournal
*)pJfd
;
270 if( ALWAYS(size
==0) ){
271 memjrnlFreeChunks(p
);
273 p
->endpoint
.pChunk
= 0;
274 p
->endpoint
.iOffset
= 0;
275 p
->readpoint
.pChunk
= 0;
276 p
->readpoint
.iOffset
= 0;
284 static int memjrnlClose(sqlite3_file
*pJfd
){
285 MemJournal
*p
= (MemJournal
*)pJfd
;
286 memjrnlFreeChunks(p
);
293 ** If the real file has been created, call its xSync method. Otherwise,
294 ** syncing an in-memory journal is a no-op.
296 static int memjrnlSync(sqlite3_file
*pJfd
, int flags
){
297 UNUSED_PARAMETER2(pJfd
, flags
);
302 ** Query the size of the file in bytes.
304 static int memjrnlFileSize(sqlite3_file
*pJfd
, sqlite_int64
*pSize
){
305 MemJournal
*p
= (MemJournal
*)pJfd
;
306 *pSize
= (sqlite_int64
) p
->endpoint
.iOffset
;
311 ** Table of methods for MemJournal sqlite3_file object.
313 static const struct sqlite3_io_methods MemJournalMethods
= {
315 memjrnlClose
, /* xClose */
316 memjrnlRead
, /* xRead */
317 memjrnlWrite
, /* xWrite */
318 memjrnlTruncate
, /* xTruncate */
319 memjrnlSync
, /* xSync */
320 memjrnlFileSize
, /* xFileSize */
323 0, /* xCheckReservedLock */
324 0, /* xFileControl */
326 0, /* xDeviceCharacteristics */
336 ** Open a journal file.
338 ** The behaviour of the journal file depends on the value of parameter
339 ** nSpill. If nSpill is 0, then the journal file is always create and
340 ** accessed using the underlying VFS. If nSpill is less than zero, then
341 ** all content is always stored in main-memory. Finally, if nSpill is a
342 ** positive value, then the journal file is initially created in-memory
343 ** but may be flushed to disk later on. In this case the journal file is
344 ** flushed to disk either when it grows larger than nSpill bytes in size,
345 ** or when sqlite3JournalCreate() is called.
347 int sqlite3JournalOpen(
348 sqlite3_vfs
*pVfs
, /* The VFS to use for actual file I/O */
349 const char *zName
, /* Name of the journal file */
350 sqlite3_file
*pJfd
, /* Preallocated, blank file handle */
351 int flags
, /* Opening flags */
352 int nSpill
/* Bytes buffered before opening the file */
354 MemJournal
*p
= (MemJournal
*)pJfd
;
356 /* Zero the file-handle object. If nSpill was passed zero, initialize
357 ** it using the sqlite3OsOpen() function of the underlying VFS. In this
358 ** case none of the code in this module is executed as a result of calls
359 ** made on the journal file-handle. */
360 memset(p
, 0, sizeof(MemJournal
));
362 return sqlite3OsOpen(pVfs
, zName
, pJfd
, flags
, 0);
366 p
->nChunkSize
= nSpill
;
368 p
->nChunkSize
= 8 + MEMJOURNAL_DFLT_FILECHUNKSIZE
- sizeof(FileChunk
);
369 assert( MEMJOURNAL_DFLT_FILECHUNKSIZE
==fileChunkSize(p
->nChunkSize
) );
372 p
->pMethod
= (const sqlite3_io_methods
*)&MemJournalMethods
;
381 ** Open an in-memory journal file.
383 void sqlite3MemJournalOpen(sqlite3_file
*pJfd
){
384 sqlite3JournalOpen(0, 0, pJfd
, 0, -1);
387 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
389 ** If the argument p points to a MemJournal structure that is not an
390 ** in-memory-only journal file (i.e. is one that was opened with a +ve
391 ** nSpill parameter), and the underlying file has not yet been created,
394 int sqlite3JournalCreate(sqlite3_file
*p
){
396 if( p
->pMethods
==&MemJournalMethods
&& ((MemJournal
*)p
)->nSpill
>0 ){
397 rc
= memjrnlCreateFile((MemJournal
*)p
);
404 ** The file-handle passed as the only argument is open on a journal file.
405 ** Return true if this "journal file" is currently stored in heap memory,
406 ** or false otherwise.
408 int sqlite3JournalIsInMemory(sqlite3_file
*p
){
409 return p
->pMethods
==&MemJournalMethods
;
413 ** Return the number of bytes required to store a JournalFile that uses vfs
414 ** pVfs to create the underlying on-disk files.
416 int sqlite3JournalSize(sqlite3_vfs
*pVfs
){
417 return MAX(pVfs
->szOsFile
, (int)sizeof(MemJournal
));