/ Check-in [3e66ea6f]
Login

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

Overview
Comment:Add hyperlink anchors to the lockingv3.html document. (CVS 3685)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 3e66ea6f61abc0f95af3bb46ebc0e10b4dcd069b
User & Date: drh 2007-03-13 16:33:43
Context
2007-03-14
15:37
Modify the behaviour of writable_schema to ignore schema parsing errors. (CVS 3686) check-in: a8d6d935 user: danielk1977 tags: trunk
2007-03-13
16:33
Add hyperlink anchors to the lockingv3.html document. (CVS 3685) check-in: 3e66ea6f user: drh tags: trunk
16:32
Do not crash when a corrupt database contains two indices with the same name. (CVS 3684) check-in: 48b2a400 user: danielk1977 tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to www/lockingv3.tcl.

     1      1   #
     2      2   # Run this script to generated a lockingv3.html output file
     3      3   #
     4      4   set rcsid {$Id: }
     5      5   source common.tcl
     6      6   header {File Locking And Concurrency In SQLite Version 3}
     7      7   
     8         -proc HEADING {level title} {
            8  +proc HEADING {level title {label {}}} {
     9      9     global pnum
    10     10     incr pnum($level)
    11     11     foreach i [array names pnum] {
    12     12       if {$i>$level} {set pnum($i) 0}
    13     13     }
    14     14     set h [expr {$level+1}]
    15     15     if {$h>6} {set h 6}
    16     16     set n $pnum(1).$pnum(2)
    17     17     for {set i 3} {$i<=$level} {incr i} {
    18     18       append n .$pnum($i)
    19     19     }
           20  +  if {$label!=""} {
           21  +    puts "<a name=\"$label\">"
           22  +  }
    20     23     puts "<h$h>$n $title</h$h>"
    21     24   }
    22     25   set pnum(1) 0
    23     26   set pnum(2) 0
    24     27   set pnum(3) 0
    25     28   set pnum(4) 0
    26     29   set pnum(5) 0
................................................................................
    38     41   This document describes the new locking mechanism.
    39     42   The intended audience is programmers who want to understand and/or modify
    40     43   the pager code and reviewers working to verify the design
    41     44   of SQLite version 3.
    42     45   </p>
    43     46   }
    44     47   
    45         -HEADING 1 {Overview}
           48  +HEADING 1 {Overview} overview
    46     49   
    47     50   puts {
    48     51   <p>
    49     52   Locking and concurrency control are handled by the the 
    50     53   <a href="http://www.sqlite.org/cvstrac/getfile/sqlite/src/pager.c">
    51     54   pager module</a>.
    52     55   The pager module is responsible for making SQLite "ACID" (Atomic,
................................................................................
    77     80   
    78     81   <p>The pager module effectively controls access for separate threads, or
    79     82   separate processes, or both.  Throughout this document whenever the
    80     83   word "process" is written you may substitute the word "thread" without
    81     84   changing the truth of the statement.</p>
    82     85   }
    83     86   
    84         -HEADING 1 {Locking}
           87  +HEADING 1 {Locking} locking
    85     88   
    86     89   puts {
    87     90   <p>
    88     91   From the point of view of a single process, a database file
    89     92   can be in one of five locking states:
    90     93   </p>
    91     94   
................................................................................
   145    148   The pager module only tracks four of the five locking states.
   146    149   A PENDING lock is always just a temporary
   147    150   stepping stone on the path to an EXCLUSIVE lock and so the pager module
   148    151   does not track PENDING locks.
   149    152   </p>
   150    153   }
   151    154   
   152         -HEADING 1 {The Rollback Journal}
          155  +HEADING 1 {The Rollback Journal} rollback
   153    156   
   154    157   puts {
   155    158   <p>Any time a process wants to make a changes to a database file, it
   156    159   first records enough information in the <em>rollback journal</em> to
   157    160   restore the database file back to its initial condition.  Thus, before
   158    161   altering any page of the database, the original contents of that page
   159    162   must be written into the journal.  The journal also records the initial
................................................................................
   209    212           empty string, and</li>
   210    213       <li>There is no RESERVED lock on the corresponding database file.</li>
   211    214       </ul>
   212    215   </li>
   213    216   </ul>
   214    217   }
   215    218   
   216         -HEADING 2 {Dealing with hot journals}
          219  +HEADING 2 {Dealing with hot journals} hot_journals
   217    220   
   218    221   puts {
   219    222   <p>
   220    223   Before reading from a a database file, SQLite always checks to see if that
   221    224   database file has a hot journal.  If the file does have a hot journal, then
   222    225   the journal is rolled back before the file is read.  In this way, we ensure
   223    226   that the database file is in a consistent state before it is read.
................................................................................
   253    256   </ol>
   254    257   
   255    258   <p>After the algorithm above completes successfully, it is safe to 
   256    259   read from the database file.  Once all reading has completed, the
   257    260   SHARED lock is dropped.</p>
   258    261   }
   259    262   
   260         -HEADING 2 {Deleting stale master journals}
          263  +HEADING 2 {Deleting stale master journals} stale_master_journals
   261    264   
   262    265   puts {
   263    266   <p>A stale master journal is a master journal that is no longer being
   264    267   used for anything.  There is no requirement that stale master journals
   265    268   be deleted.  The only reason for doing so is to free up disk space.</p>
   266    269   
   267    270   <p>A master journal is stale if no individual file journals are pointing
................................................................................
   270    273   we check each of those file journals.  If any of the file journals named
   271    274   in the master journal exists and points back to the master journal, then
   272    275   the master journal is not stale.  If all file journals are either missing
   273    276   or refer to other master journals or no master journal at all, then the
   274    277   master journal we are testing is stale and can be safely deleted.</p>
   275    278   }
   276    279   
   277         -HEADING 1 {Writing to a database file}
          280  +HEADING 1 {Writing to a database file} writing
   278    281   
   279    282   puts {
   280    283   <p>To write to a database, a process must first acquire a SHARED lock
   281    284   as described above (possibly rolling back incomplete changes if there
   282    285   is a hot journal). 
   283    286   After a SHARED lock is obtained, a RESERVED lock must be acquired.
   284    287   The RESERVED lock signals that the process intends to write to the
................................................................................
   397    400       </li>
   398    401   <li>Delete all individual journal files.
   399    402   <li>Drop the EXCLUSIVE and PENDING locks from all database files.
   400    403       </li>
   401    404   </ol>
   402    405   }
   403    406   
   404         -HEADING 2 {Writer starvation}
          407  +HEADING 2 {Writer starvation} writer_starvation
   405    408   
   406    409   puts {
   407    410   <p>In SQLite version 2, if many processes are reading from the database,
   408    411   it might be the case that there is never a time when there are
   409    412   no active readers.  And if there is always at least one read lock on the
   410    413   database, no process would ever be able to make changes to the database
   411    414   because it would be impossible to acquire a write lock.  This situation
................................................................................
   416    419   but prevents new readers from connecting to the database.  So when a
   417    420   process wants to write a busy database, it can set a PENDING lock which
   418    421   will prevent new readers from coming in.  Assuming existing readers do
   419    422   eventually complete, all SHARED locks will eventually clear and the
   420    423   writer will be given a chance to make its changes.</p>
   421    424   }
   422    425   
   423         -HEADING 1 {How To Corrupt Your Database Files}
          426  +HEADING 1 {How To Corrupt Your Database Files} how_to_corrupt
   424    427   
   425    428   puts {
   426    429   <p>The pager module is robust but it is not completely failsafe.
   427    430   It can be subverted.  This section attempts to identify and explain
   428    431   the risks.</p>
   429    432   
   430    433   <p>
................................................................................
   511    514   All databases will continue to be self-consistent.
   512    515   To defend against this problem, keep all databases
   513    516   on the same disk volume and/or remount disks using exactly the same names
   514    517   after a power failure.
   515    518   </p>
   516    519   }
   517    520   
   518         -HEADING 1 {Transaction Control At The SQL Level}
          521  +HEADING 1 {Transaction Control At The SQL Level} transaction_control
   519    522   
   520    523   puts {
   521    524   <p>
   522    525   The changes to locking and concurrency control in SQLite version 3 also
   523    526   introduce some subtle changes in the way transactions work at the SQL
   524    527   language level.
   525    528   By default, SQLite version 3 operates in <em>autocommit</em> mode.