src/memjournal.c

   1 /*
   2 ** 2008 October 7
   3 **
   4 ** The author disclaims copyright to this source code.  In place of
   5 ** a legal notice, here is a blessing:
   6 **
   7 **    May you do good and not evil.
   8 **    May you find forgiveness for yourself and forgive others.
   9 **    May you share freely, never taking more than you give.
  10 **
  11 *************************************************************************
  12 **
  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.
  16 **
  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
  24 ** occur.
  25 */
  26 #include "sqliteInt.h"
  27
  28 /* Forward references to internal structures */
  29 typedef struct MemJournal MemJournal;
  30 typedef struct FilePoint FilePoint;
  31 typedef struct FileChunk FileChunk;
  32
  33 /*
  34 ** The rollback journal is composed of a linked list of these structures.
  35 **
  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.
  38 */
  39 struct FileChunk {
  40   FileChunk *pNext;               /* Next chunk in the journal */
  41   u8 zChunk[8];                   /* Content of this chunk */
  42 };
  43
  44 /*
  45 ** By default, allocate this many bytes of memory for each FileChunk object.
  46 */
  47 #define MEMJOURNAL_DFLT_FILECHUNKSIZE 1024
  48
  49 /*
  50 ** For chunk size nChunkSize, return the number of bytes that should
  51 ** be allocated for each FileChunk structure.
  52 */
  53 #define fileChunkSize(nChunkSize) (sizeof(FileChunk) + ((nChunkSize)-8))
  54
  55 /*
  56 ** An instance of this object serves as a cursor into the rollback journal.
  57 ** The cursor can be either for reading or writing.
  58 */
  59 struct FilePoint {
  60   sqlite3_int64 iOffset;          /* Offset from the beginning of the file */
  61   FileChunk *pChunk;              /* Specific chunk into which cursor points */
  62 };
  63
  64 /*
  65 ** This structure is a subclass of sqlite3_file. Each open memory-journal
  66 ** is an instance of this class.
  67 */
  68 struct MemJournal {
  69   const sqlite3_io_methods *pMethod; /* Parent class. MUST BE FIRST */
  70   int nChunkSize;                 /* In-memory chunk-size */
  71
  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() */
  77
  78   int flags;                      /* xOpen flags */
  79   sqlite3_vfs *pVfs;              /* The "real" underlying VFS */
  80   const char *zJournal;           /* Name of the journal file */
  81 };
  82
  83 /*
  84 ** Read data from the in-memory journal file.  This is the implementation
  85 ** of the sqlite3_vfs.xRead method.
  86 */
  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 */
  92 ){
  93   MemJournal *p = (MemJournal *)pJfd;
  94   u8 *zOut = zBuf;
  95   int nRead = iAmt;
  96   int iChunkOffset;
  97   FileChunk *pChunk;
  98
  99 #if defined(SQLITE_ENABLE_ATOMIC_WRITE) \
 100  || defined(SQLITE_ENABLE_BATCH_ATOMIC_WRITE)
 101   if( (iAmt+iOfst)>p->endpoint.iOffset ){
 102     return SQLITE_IOERR_SHORT_READ;
 103   }
 104 #endif
 105
 106   assert( (iAmt+iOfst)<=p->endpoint.iOffset );
 107   assert( p->readpoint.iOffset==0 || p->readpoint.pChunk!=0 );
 108   if( p->readpoint.iOffset!=iOfst || iOfst==0 ){
 109     sqlite3_int64 iOff = 0;
 110     for(pChunk=p->pFirst;
 111         ALWAYS(pChunk) && (iOff+p->nChunkSize)<=iOfst;
 112         pChunk=pChunk->pNext
 113     ){
 114       iOff += p->nChunkSize;
 115     }
 116   }else{
 117     pChunk = p->readpoint.pChunk;
 118     assert( pChunk!=0 );
 119   }
 120
 121   iChunkOffset = (int)(iOfst%p->nChunkSize);
 122   do {
 123     int iSpace = p->nChunkSize - iChunkOffset;
 124     int nCopy = MIN(nRead, (p->nChunkSize - iChunkOffset));
 125     memcpy(zOut, (u8*)pChunk->zChunk + iChunkOffset, nCopy);
 126     zOut += nCopy;
 127     nRead -= iSpace;
 128     iChunkOffset = 0;
 129   } while( nRead>=0 && (pChunk=pChunk->pNext)!=0 && nRead>0 );
 130   p->readpoint.iOffset = pChunk ? iOfst+iAmt : 0;
 131   p->readpoint.pChunk = pChunk;
 132
 133   return SQLITE_OK;
 134 }
 135
 136 /*
 137 ** Free the list of FileChunk structures headed at MemJournal.pFirst.
 138 */
 139 static void memjrnlFreeChunks(MemJournal *p){
 140   FileChunk *pIter;
 141   FileChunk *pNext;
 142   for(pIter=p->pFirst; pIter; pIter=pNext){
 143     pNext = pIter->pNext;
 144     sqlite3_free(pIter);
 145   }
 146   p->pFirst = 0;
 147 }
 148
 149 /*
 150 ** Flush the contents of memory to a real file on disk.
 151 */
 152 static int memjrnlCreateFile(MemJournal *p){
 153   int rc;
 154   sqlite3_file *pReal = (sqlite3_file*)p;
 155   MemJournal copy = *p;
 156
 157   memset(p, 0, sizeof(MemJournal));
 158   rc = sqlite3OsOpen(copy.pVfs, copy.zJournal, pReal, copy.flags, 0);
 159   if( rc==SQLITE_OK ){
 160     int nChunk = copy.nChunkSize;
 161     i64 iOff = 0;
 162     FileChunk *pIter;
 163     for(pIter=copy.pFirst; pIter; pIter=pIter->pNext){
 164       if( iOff + nChunk > copy.endpoint.iOffset ){
 165         nChunk = copy.endpoint.iOffset - iOff;
 166       }
 167       rc = sqlite3OsWrite(pReal, (u8*)pIter->zChunk, nChunk, iOff);
 168       if( rc ) break;
 169       iOff += nChunk;
 170     }
 171     if( rc==SQLITE_OK ){
 172       /* No error has occurred. Free the in-memory buffers. */
 173       memjrnlFreeChunks(&copy);
 174     }
 175   }
 176   if( rc!=SQLITE_OK ){
 177     /* If an error occurred while creating or writing to the file, restore
 178     ** the original before returning. This way, SQLite uses the in-memory
 179     ** journal data to roll back changes made to the internal page-cache
 180     ** before this function was called.  */
 181     sqlite3OsClose(pReal);
 182     *p = copy;
 183   }
 184   return rc;
 185 }
 186
 187
 188 /*
 189 ** Write data to the file.
 190 */
 191 static int memjrnlWrite(
 192   sqlite3_file *pJfd,    /* The journal file into which to write */
 193   const void *zBuf,      /* Take data to be written from here */
 194   int iAmt,              /* Number of bytes to write */
 195   sqlite_int64 iOfst     /* Begin writing at this offset into the file */
 196 ){
 197   MemJournal *p = (MemJournal *)pJfd;
 198   int nWrite = iAmt;
 199   u8 *zWrite = (u8 *)zBuf;
 200
 201   /* If the file should be created now, create it and write the new data
 202   ** into the file on disk. */
 203   if( p->nSpill>0 && (iAmt+iOfst)>p->nSpill ){
 204     int rc = memjrnlCreateFile(p);
 205     if( rc==SQLITE_OK ){
 206       rc = sqlite3OsWrite(pJfd, zBuf, iAmt, iOfst);
 207     }
 208     return rc;
 209   }
 210
 211   /* If the contents of this write should be stored in memory */
 212   else{
 213     /* An in-memory journal file should only ever be appended to. Random
 214     ** access writes are not required. The only exception to this is when
 215     ** the in-memory journal is being used by a connection using the
 216     ** atomic-write optimization. In this case the first 28 bytes of the
 217     ** journal file may be written as part of committing the transaction. */
 218     assert( iOfst==p->endpoint.iOffset || iOfst==0 );
 219 #if defined(SQLITE_ENABLE_ATOMIC_WRITE) \
 220  || defined(SQLITE_ENABLE_BATCH_ATOMIC_WRITE)
 221     if( iOfst==0 && p->pFirst ){
 222       assert( p->nChunkSize>iAmt );
 223       memcpy((u8*)p->pFirst->zChunk, zBuf, iAmt);
 224     }else
 225 #else
 226     assert( iOfst>0 || p->pFirst==0 );
 227 #endif
 228     {
 229       while( nWrite>0 ){
 230         FileChunk *pChunk = p->endpoint.pChunk;
 231         int iChunkOffset = (int)(p->endpoint.iOffset%p->nChunkSize);
 232         int iSpace = MIN(nWrite, p->nChunkSize - iChunkOffset);
 233
 234         if( iChunkOffset==0 ){
 235           /* New chunk is required to extend the file. */
 236           FileChunk *pNew = sqlite3_malloc(fileChunkSize(p->nChunkSize));
 237           if( !pNew ){
 238             return SQLITE_IOERR_NOMEM_BKPT;
 239           }
 240           pNew->pNext = 0;
 241           if( pChunk ){
 242             assert( p->pFirst );
 243             pChunk->pNext = pNew;
 244           }else{
 245             assert( !p->pFirst );
 246             p->pFirst = pNew;
 247           }
 248           p->endpoint.pChunk = pNew;
 249         }
 250
 251         memcpy((u8*)p->endpoint.pChunk->zChunk + iChunkOffset, zWrite, iSpace);
 252         zWrite += iSpace;
 253         nWrite -= iSpace;
 254         p->endpoint.iOffset += iSpace;
 255       }
 256       p->nSize = iAmt + iOfst;
 257     }
 258   }
 259
 260   return SQLITE_OK;
 261 }
 262
 263 /*
 264 ** Truncate the file.
 265 **
 266 ** If the journal file is already on disk, truncate it there. Or, if it
 267 ** is still in main memory but is being truncated to zero bytes in size,
 268 ** ignore
 269 */
 270 static int memjrnlTruncate(sqlite3_file *pJfd, sqlite_int64 size){
 271   MemJournal *p = (MemJournal *)pJfd;
 272   if( ALWAYS(size==0) ){
 273     memjrnlFreeChunks(p);
 274     p->nSize = 0;
 275     p->endpoint.pChunk = 0;
 276     p->endpoint.iOffset = 0;
 277     p->readpoint.pChunk = 0;
 278     p->readpoint.iOffset = 0;
 279   }
 280   return SQLITE_OK;
 281 }
 282
 283 /*
 284 ** Close the file.
 285 */
 286 static int memjrnlClose(sqlite3_file *pJfd){
 287   MemJournal *p = (MemJournal *)pJfd;
 288   memjrnlFreeChunks(p);
 289   return SQLITE_OK;
 290 }
 291
 292 /*
 293 ** Sync the file.
 294 **
 295 ** If the real file has been created, call its xSync method. Otherwise,
 296 ** syncing an in-memory journal is a no-op.
 297 */
 298 static int memjrnlSync(sqlite3_file *pJfd, int flags){
 299   UNUSED_PARAMETER2(pJfd, flags);
 300   return SQLITE_OK;
 301 }
 302
 303 /*
 304 ** Query the size of the file in bytes.
 305 */
 306 static int memjrnlFileSize(sqlite3_file *pJfd, sqlite_int64 *pSize){
 307   MemJournal *p = (MemJournal *)pJfd;
 308   *pSize = (sqlite_int64) p->endpoint.iOffset;
 309   return SQLITE_OK;
 310 }
 311
 312 /*
 313 ** Table of methods for MemJournal sqlite3_file object.
 314 */
 315 static const struct sqlite3_io_methods MemJournalMethods = {
 316   1,                /* iVersion */
 317   memjrnlClose,     /* xClose */
 318   memjrnlRead,      /* xRead */
 319   memjrnlWrite,     /* xWrite */
 320   memjrnlTruncate,  /* xTruncate */
 321   memjrnlSync,      /* xSync */
 322   memjrnlFileSize,  /* xFileSize */
 323   0,                /* xLock */
 324   0,                /* xUnlock */
 325   0,                /* xCheckReservedLock */
 326   0,                /* xFileControl */
 327   0,                /* xSectorSize */
 328   0,                /* xDeviceCharacteristics */
 329   0,                /* xShmMap */
 330   0,                /* xShmLock */
 331   0,                /* xShmBarrier */
 332   0,                /* xShmUnmap */
 333   0,                /* xFetch */
 334   0                 /* xUnfetch */
 335 };
 336
 337 /*
 338 ** Open a journal file.
 339 **
 340 ** The behaviour of the journal file depends on the value of parameter
 341 ** nSpill. If nSpill is 0, then the journal file is always create and
 342 ** accessed using the underlying VFS. If nSpill is less than zero, then
 343 ** all content is always stored in main-memory. Finally, if nSpill is a
 344 ** positive value, then the journal file is initially created in-memory
 345 ** but may be flushed to disk later on. In this case the journal file is
 346 ** flushed to disk either when it grows larger than nSpill bytes in size,
 347 ** or when sqlite3JournalCreate() is called.
 348 */
 349 int sqlite3JournalOpen(
 350   sqlite3_vfs *pVfs,         /* The VFS to use for actual file I/O */
 351   const char *zName,         /* Name of the journal file */
 352   sqlite3_file *pJfd,        /* Preallocated, blank file handle */
 353   int flags,                 /* Opening flags */
 354   int nSpill                 /* Bytes buffered before opening the file */
 355 ){
 356   MemJournal *p = (MemJournal*)pJfd;
 357
 358   /* Zero the file-handle object. If nSpill was passed zero, initialize
 359   ** it using the sqlite3OsOpen() function of the underlying VFS. In this
 360   ** case none of the code in this module is executed as a result of calls
 361   ** made on the journal file-handle.  */
 362   memset(p, 0, sizeof(MemJournal));
 363   if( nSpill==0 ){
 364     return sqlite3OsOpen(pVfs, zName, pJfd, flags, 0);
 365   }
 366
 367   if( nSpill>0 ){
 368     p->nChunkSize = nSpill;
 369   }else{
 370     p->nChunkSize = 8 + MEMJOURNAL_DFLT_FILECHUNKSIZE - sizeof(FileChunk);
 371     assert( MEMJOURNAL_DFLT_FILECHUNKSIZE==fileChunkSize(p->nChunkSize) );
 372   }
 373
 374   p->pMethod = (const sqlite3_io_methods*)&MemJournalMethods;
 375   p->nSpill = nSpill;
 376   p->flags = flags;
 377   p->zJournal = zName;
 378   p->pVfs = pVfs;
 379   return SQLITE_OK;
 380 }
 381
 382 /*
 383 ** Open an in-memory journal file.
 384 */
 385 void sqlite3MemJournalOpen(sqlite3_file *pJfd){
 386   sqlite3JournalOpen(0, 0, pJfd, 0, -1);
 387 }
 388
 389 #if defined(SQLITE_ENABLE_ATOMIC_WRITE) \
 390  || defined(SQLITE_ENABLE_BATCH_ATOMIC_WRITE)
 391 /*
 392 ** If the argument p points to a MemJournal structure that is not an
 393 ** in-memory-only journal file (i.e. is one that was opened with a +ve
 394 ** nSpill parameter or as SQLITE_OPEN_MAIN_JOURNAL), and the underlying
 395 ** file has not yet been created, create it now.
 396 */
 397 int sqlite3JournalCreate(sqlite3_file *pJfd){
 398   int rc = SQLITE_OK;
 399   MemJournal *p = (MemJournal*)pJfd;
 400   if( p->pMethod==&MemJournalMethods && (
 401 #ifdef SQLITE_ENABLE_ATOMIC_WRITE
 402      p->nSpill>0
 403 #else
 404      /* While this appears to not be possible without ATOMIC_WRITE, the
 405      ** paths are complex, so it seems prudent to leave the test in as
 406      ** a NEVER(), in case our analysis is subtly flawed. */
 407      NEVER(p->nSpill>0)
 408 #endif
 409 #ifdef SQLITE_ENABLE_BATCH_ATOMIC_WRITE
 410      || (p->flags & SQLITE_OPEN_MAIN_JOURNAL)
 411 #endif
 412   )){
 413     rc = memjrnlCreateFile(p);
 414   }
 415   return rc;
 416 }
 417 #endif
 418
 419 /*
 420 ** The file-handle passed as the only argument is open on a journal file.
 421 ** Return true if this "journal file" is currently stored in heap memory,
 422 ** or false otherwise.
 423 */
 424 int sqlite3JournalIsInMemory(sqlite3_file *p){
 425   return p->pMethods==&MemJournalMethods;
 426 }
 427
 428 /*
 429 ** Return the number of bytes required to store a JournalFile that uses vfs
 430 ** pVfs to create the underlying on-disk files.
 431 */
 432 int sqlite3JournalSize(sqlite3_vfs *pVfs){
 433   return MAX(pVfs->szOsFile, (int)sizeof(MemJournal));
 434 }