Documentation Source Text

Check-in [1276228968]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Add assumptions for "safe-append" and "atomic-write" VFS implementations.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 1276228968d51d4de9e0b0e667cc37c4c30201cb
User & Date: dan 2008-07-30 18:30:59
Context
2008-07-31
10:57
Add a "document structure" section to fileio.in. check-in: 92809645e2 user: dan tags: trunk
2008-07-30
18:30
Add assumptions for "safe-append" and "atomic-write" VFS implementations. check-in: 1276228968 user: dan tags: trunk
09:00
Add a better overview to fileio.in. check-in: f0560b2aa4 user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/fileio.in.

142
143
144
145
146
147
148



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166




167
168
169
170
171
172
173
174
175
176
177
178
179
...
299
300
301
302
303
304
305
306




307
308
309
310
311
312
313
...
426
427
428
429
430
431
432
433
434
435
436

437
438






439
























440
441
442
443
444
445
446
447
448
449
450
451
452
453
    This document does not specify the details of the interface that must
    be implemented by the VFS adaptor component, that is left to
    <cite>capi_sqlitert_requirements</cite>.
    


  <h2>Document Organization</h2>



  <h2>Glossary</h2>
    <p class=todo>
      After this document is ready, make the vocabulary consistent and
      then add a glossary here.

<h1>VFS Adaptor Related Assumptions</h1>

  <h2>SQLite File-System Usage </h2>
    <p>
      SQLite uses the file-system service made available via the 
      <i>VFS adaptor</i> to create, read and modify three different types
      of files, as follows:

    <ul>
      <li> database files,
      <li> journal files, and
      <li> master journal files.
    </ul>





    <p>
      A database file is a file-system file used to store an SQLite database 
      image (see <cite>ff_sqlitert_requirements</cite>).

  <h2>Performance Related Assumptions</h2>

  <h2 id=fs_characteristics>System Failure Related Assumptions</h2>
    <p>
      In the event of an operating system or power failure, the various 
      combinations of file-system and storage hardware available provide
      varying levels of guarantee as to the integrity of the data written
      to the file system just before or during the failure. The exact
................................................................................
		 sector may be partially written, completely written, not
                 written at all or populated with garbage data,
            <li> the remaining operations will not have had any effect on
                 the contents of the file-system.
          </ol> 
    </ul>

    <h3>Details</h3>





    <p>
      This section describes how the assumptions presented in the parent
      section apply to the individual API functions and operations provided 
      by the VFS to SQLite for the purposes of modifying the contents of the
      file-system.

................................................................................
      be made persistent until after the corresponding file has been
      <i>synced</i>.

    ASSUMPTION A21008
      If a system failure occurs during or after a "write file"
      operation, but before the corresponding file has been <i>synced</i>, 
      then it is assumed that the content of all sectors spanned by the
      <i>write file</i> operation is assumed to be untrustworthy following
      system recovery. This includes regions of the sectors that were not
      actually modified by the write file operation. It is assumed that it
      is possible that the sector data was written correctly, partially,

      or not at all, or that the sector has been completely or partially
      filled with random data.































    ASSUMPTION A21009
      If a system failure occurs during or after a "write file"
      operation that causes the file to grow, but before the corresponding 
      file has been <i>synced</i>, then it is assumed 
      that the size of the file following recovery is as large or larger
      than it was before the "write file" operation that, if successful,
      would cause the file to grow.

<!--
    <p>
      The return value of the xSectorSize() method, the <i>sector-size</i>, is
      expected by SQLite to be a power of 2 value greater than or equal to 512.

    <p class=todo> 







>
>
>







|
<
<
<
<

<
<
<
<
<
>
>
>
>

<
<
<
<
<







 







|
>
>
>
>







 







|
|
|
<
>
|
|
>
>
>
>
>
>

>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>



|
|
|
|







142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159




160





161
162
163
164
165





166
167
168
169
170
171
172
...
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
...
423
424
425
426
427
428
429
430
431
432

433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
    This document does not specify the details of the interface that must
    be implemented by the VFS adaptor component, that is left to
    <cite>capi_sqlitert_requirements</cite>.
    


  <h2>Document Organization</h2>
    <p class=todo>
      Add this section describing what is to come.

  <h2>Glossary</h2>
    <p class=todo>
      After this document is ready, make the vocabulary consistent and
      then add a glossary here.

<h1>VFS Adaptor Related Assumptions</h1>

  <h2>Performance Related Assumptions</h2>










    ASSUMPTION A21010
      It is assumed that writing a series of sequential blocks of data to 
      a file in order is faster than writing the same blocks in an arbitrary
      order.







  <h2 id=fs_characteristics>System Failure Related Assumptions</h2>
    <p>
      In the event of an operating system or power failure, the various 
      combinations of file-system and storage hardware available provide
      varying levels of guarantee as to the integrity of the data written
      to the file system just before or during the failure. The exact
................................................................................
		 sector may be partially written, completely written, not
                 written at all or populated with garbage data,
            <li> the remaining operations will not have had any effect on
                 the contents of the file-system.
          </ol> 
    </ul>

    <h3>Failure Related Assumption Details</h3>

    <p class=todo>
      Modify assumptions in this section to take the <i>sequential-write</i>
      characteristic into account.

    <p>
      This section describes how the assumptions presented in the parent
      section apply to the individual API functions and operations provided 
      by the VFS to SQLite for the purposes of modifying the contents of the
      file-system.

................................................................................
      be made persistent until after the corresponding file has been
      <i>synced</i>.

    ASSUMPTION A21008
      If a system failure occurs during or after a "write file"
      operation, but before the corresponding file has been <i>synced</i>, 
      then it is assumed that the content of all sectors spanned by the
      <i>write file</i> operation are untrustworthy following system 
      recovery. This includes regions of the sectors that were not
      actually modified by the write file operation.


    ASSUMPTION A21011
      If a system failure occurs on a system that supports the 
      <i>atomic-write</i> property for blocks of size <i>N</i> bytes,
      and a system failure occurs following an aligned write of <i>N</i> 
      bytes to a file but before the file has been succesfully <i>synced</i>,
      then is is assumed following recovery that all sectors spanned by the
      write operation were correctly updated, or that none of the sectors were
      modified at all.

    ASSUMPTION A21012
      If a system failure occurs on a system that supports the 
      <i>safe-append</i> following a write operation that appends data
      to the end of the file without modifying any of the existing file 
      content but before the file has been succesfully <i>synced</i>,
      then is is assumed following recovery that either the data was
      correctly appended to the file, or that the file size remains 
      unchanged. It is assumed that it is impossible that the file be
      extended but populated with incorrect data.
      
    ASSUMPTION A21013
      Following a system recovery, if a device sector is deemed to be
      untrustworthy as defined by A21008 and neither A21011 or A21012 
      apply to the range of bytes written, then no assumption can be
      made about the content of the sector following recovery. It is
      assumed that it is possible for such a sector to be written 
      correctly, not written at all, populated with garbage data or any
      combination thereof.

    <p class=todo>
      Fix the requirement below. The idea is to say that extending a file
      cannot cause the file size to become corrupted and thereby cause the
      whole file to be lost.

    ASSUMPTION A21009
      If a system failure occurs during or after a "write file"
      operation that causes the file to grow, but before the corresponding 
      file has been <i>synced</i>, then it is assumed that the size of 
      the file following recovery is as large or larger than it was before 
      the "write file" operation that, if successful, would cause the file 
      to grow.

<!--
    <p>
      The return value of the xSectorSize() method, the <i>sector-size</i>, is
      expected by SQLite to be a power of 2 value greater than or equal to 512.

    <p class=todo>