Documentation Source Text

Check-in [7274af9a66]
Login

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

Overview
Comment:Progress on btreemodule.html
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:7274af9a66e9fd8e700f29f3c7db5c3e19f0a696
User & Date: dan 2009-05-30 11:45:03
Context
2009-06-01
12:04
Work on b-tree requirements. check-in: fdf074286b user: dan tags: trunk
2009-05-30
11:45
Progress on btreemodule.html check-in: 7274af9a66 user: dan tags: trunk
2009-05-29
12:12
Add hlr50000.txt. check-in: 208f3f4f7c user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/btreemodule.in.

    49     49   
    50     50     [h2 "Document and Requirements Organization"]
    51     51   
    52     52        [Table]
    53     53           [Tr] <th> Requirement ids <th> Contents
    54     54           [Tr] <td> H50**** <td> Requirement statements specifying the functionality required of the B-Tree module.
    55     55           [Tr] <td> H51**** <td> Requirement statements specifying the API provided by the B-Tree module.
    56         -        [Tr] <td>         <td> Requirement statements specifying some details of the internal workings of the B-Tree module.
           56  +        [Tr] <td> L****** <td> Requirement statements specifying some details of the internal workings of the B-Tree module.
    57     57         </table>
    58     58   
    59     59     [h2 "Glossary"]
    60     60   
    61     61       <table id=glossary>
    62     62         [Glossary "B-Tree Database Connection" {
    63     63           A B-Tree database connection is a single client connection to an in-memory 
................................................................................
    71     71         [Glossary "Page cache" {
    72     72         }]
    73     73         [Glossary "Persistent database" {
    74     74         }]
    75     75         [Glossary "Read-through cache" {
    76     76         }]
    77     77         [Glossary "Shared-cache mode" {
           78  +      }]
           79  +      [Glossary "SQLite Error Code" {
    78     80         }]
    79     81         [Glossary "Temporary database" {
    80     82         }]
    81     83       </table>
    82     84      
    83     85   
    84     86     [h1 "Module Requirements"]
................................................................................
   155    157         following requirements, a "new database image" is defined as one that is
   156    158         zero pages in size.
   157    159   
   158    160         [fancyformat_import_requirement H50080]
   159    161         [fancyformat_import_requirement H50090]
   160    162   
   161    163       [h3 "Transaction and Savepoint Functions"]
          164  +
   162    165     <ul>
   163    166       <li> Begin transaction.
   164         -    <li> CommitPhaseOne()/CommitPhaseTwo().
   165    167       <li> Rollback transaction.
          168  +    <li> Commit transaction.
   166    169       <li> Query for transaction state (no-transaction, readonly, read-write).
   167    170       <li> Begin savepoint(s).
   168    171       <li> Release savepoint(s).
   169    172       <li> Rollback savepoint(s).
   170    173     </ul>
          174  +
          175  +    <p>
          176  +
          177  +  <ul>
          178  +    <li> CommitPhaseOne()/CommitPhaseTwo().
          179  +  </ul>
   171    180   
   172    181       [h3 "Reading From the Database Image"]
   173    182     <ul>
   174    183       <li> Open b-tree cursor.
   175    184       <li> Close b-tree cursor.
   176    185       <li> Seek cursor (and all of its variants).
   177    186       <li> Next/Prev cursor operations.
................................................................................
   274    283             <br> * To know how many savepoints are open in BtreeBeginTrans().
   275    284             <br> * Many, many times to assert() that the db mutex is held when the b-tree layer is accessed..
   276    285   
   277    286   
   278    287       [h2 "Opening and Closing Connections"]
   279    288   
   280    289       <p>
   281         -      The following two functions are used to open and close B-Tree database connections, respectively.
          290  +      This section describes the API offered by the B-Tree module to other
          291  +      SQLite sub-systems to open and close B-Tree database connections.
   282    292   
   283    293         [btree_api_defn Btree]
   284    294   
   285         -      [btree_api_defn sqlite3BtreeOpen sqlite3BtreeClose]
          295  +    <p>
          296  +      A B-Tree database connection is accessed by other SQLite sub-systems
          297  +      using an opaque handle, modelled in C code using the type "Btree*".
          298  +
          299  +      [btree_api_defn sqlite3BtreeOpen] 
          300  +
          301  +      [fancyformat_import_requirement H51001]
          302  +      [fancyformat_import_requirement H51002]
          303  +
          304  +      [fancyformat_import_requirement H51003]
          305  +      [fancyformat_import_requirement H51004]
          306  +
          307  +    <p>
          308  +      The combination of the above two requirements implies that if the
          309  +      zFilename argument passed to sqlite3BtreeOpen is other than a NULL
          310  +      pointer or a pointer to a nul-terminated string, the type of or
          311  +      filename of the database that sqlite3BtreeOpen attempts to open a
          312  +      connection to are undefined.
   286    313   
   287    314       <p>
   288         -      Valid values for the <i>flags</i> argument to the
   289         -      <i>sqlite3BtreeOpen()</i> function consist of the bitwise OR of zero or
   290         -      more of the following symbols.
          315  +      Valid values for the <i>flags</i> argument to the sqlite3BtreeOpen
          316  +      function consist of the bitwise OR of zero or more of the following
          317  +      symbols.
   291    318   
   292    319         [btree_api_defn BTREE_OMIT_JOURNAL BTREE_NO_READLOCK]
          320  +
          321  +      [fancyformat_import_requirement H51005]
          322  +
          323  +    <p>
          324  +      When opening a connection to a persistent database, the value of the
          325  +      BTREE_OMIT_JOURNAL bit in the flags parameter is ignored by
          326  +      sqlite3BtreeOpen.
          327  +
          328  +      [fancyformat_import_requirement H51006]
          329  +
          330  +    <p>
          331  +      When opening a connection to a temporary database, the value of the
          332  +      BTREE_NO_READLOCK bit in the flags parameter is ignored, as temporary
          333  +      databases are never locked for either reading or writing 
          334  +      (<span class=todo>reference to some requirement for this statement.</span>).
          335  +      Whether or not a new page-cache is created when a connection to a
          336  +      persistent database is opened is governed by requirements H50040 and
          337  +      H50050.
          338  +
          339  +      [fancyformat_import_requirement H51007]
          340  +      [fancyformat_import_requirement H51008]
          341  +
          342  +    <p class=todo>
          343  +      Requirements explaining how the db parameter to sqlite3BtreeOpen is used. Must be there for something.
          344  +
          345  +      [btree_api_defn sqlite3BtreeClose]
          346  +
          347  +      [fancyformat_import_requirement H51009]
          348  +
          349  +    <p>
          350  +      If a call to sqlite3BtreeClose is made with a value that is not a valid
          351  +      b-tree database connection handle passed as the only argument, the
          352  +      results are undefined.
          353  +
          354  +      [fancyformat_import_requirement H51010]
          355  +
          356  +    <p>
          357  +      See also requirement H50070.
          358  +
   293    359   
   294    360       [h2 "Database Image Configuration"]
   295    361   
   296    362         <p class=todo>
   297    363   	This category doesn't work all that well. These APIs are used for other
   298    364           things too (i.e. switching to incremental-vacuum mode).
   299    365   
................................................................................
   363    429   
   364    430         [btree_api_defn sqlite3BtreeBeginStmt sqlite3BtreeSavepoint]
   365    431   
   366    432         [btree_api_defn sqlite3BtreeIsInTrans sqlite3BtreeIsInReadTrans sqlite3BtreeIsInBackup]
   367    433   
   368    434       [h2 "What do these do?"]
   369    435   
          436  +    <p class=todo>
          437  +      The following is used only from within VdbeExec() to check whether or not
          438  +      a cursor was opened on a table or index b-tree. Corruption tests can move into
          439  +      the b-tree layer.
          440  +
   370    441         [btree_api_defn sqlite3BtreeFlags]
   371    442   
   372    443         <p class=todo>
   373    444           Where do the following go?
   374    445   
   375         -      [btree_api_defn sqlite3BtreeIntegrityCheck sqlite3BtreePager]
          446  +      [btree_api_defn sqlite3BtreeIntegrityCheck sqlite3BtreePager sqlite3BtreeCopyFile]
   376    447   
   377    448         [btree_api_defn sqlite3BtreeSchema sqlite3BtreeSchemaLocked sqlite3BtreeLockTable sqlite3BtreeTripAllCursors]
   378    449   
   379    450         <p class=todo>
   380    451           I know what the following do, but is this mechanism ever used? Or has it been superceded by other tricks in OP_NewRowid?
   381    452   
   382         -      [btree_api_defn sqlite3BtreeSetCachedRowid sqlite3BtreeGetCachedRowid sqlite3BtreeCopyFile]
          453  +      [btree_api_defn sqlite3BtreeSetCachedRowid sqlite3BtreeGetCachedRowid]
   383    454   
   384    455         <p class=todo>
   385    456           Should move to btreeInt.h
   386    457   
   387    458         [btree_api_defn BtShared]
   388    459   
          460  +    [h2 "APIs not branded sqlite3BtreeXXX()"]
          461  +
          462  +<ul>
          463  +<li> sqlite3PagerLockingMode
          464  +<li> sqlite3PagerJournalMode
          465  +<li> sqlite3PagerIsMemdb (vacuum and backup).
          466  +<li> sqlite3PagerJournalSizeLimit
          467  +<li> sqlite3PagerFile (used by sqlite3_file_control() and pragma lock_proxy_file).
          468  +<li> sqlite3PagerPagecounT (pragma page_count and backup).
          469  +<li> Page APIs used by backup routines:
          470  +  <ul>
          471  +    <li> sqlite3PagerGet
          472  +    <li> sqlite3PagerWrite
          473  +    <li> sqlite3PagerGetData
          474  +    <li> sqlite3PagerGetExtra
          475  +    <li> sqlite3PagerUnref
          476  +    <li> sqlite3PagerTruncateImage
          477  +    <li> sqlite3PagerSync
          478  +    <li> sqlite3PagerFile
          479  +    <li> sqlite3PagerCommitPhaseOne, sqlite3PagerCommitPhaseTwo
          480  +    <li> sqlite3PagerBackupPtr
          481  +  </ul>
          482  +</ul>
   389    483   
   390    484   
   391    485     [h1 "Module Implementation"]
   392    486   
   393    487     [h2 "Database Image Traversal and Manipulation"]
   394    488   
   395    489        <p class=todo>

Changes to req/hlr50000.txt.

    14     14   HLR H50040
    15     15   If SQLite is configured to run in shared-cache mode, and a connection is opened
    16     16   to a persistent database file for which there exists already a page-cache within 
    17     17   the current processes address space, then the connection opened shall be a
    18     18   connection to the existing page-cache.
    19     19   
    20     20   HLR H50050
    21         -If a connection to a database is opened and requirement H50020 does not apply,
           21  +If a new B-Tree database connection is opened and requirement H50040 does not apply,
    22     22   then a new page-cache shall be created within the processes address space. The
    23     23   opened connection shall be a connection to the new page-cache.
    24     24   
    25     25   HLR H50060
    26     26   The B-Tree module shall provide an interface to close a B-Tree database connection. 
    27     27   
    28     28   HLR H50070
................................................................................
    32     32   
    33     33   HLR H50080
    34     34   The B-Tree module shall provide an interface to configure the page-size of a
    35     35   new database image. 
    36     36   
    37     37   HLR H50090
    38     38   The B-Tree module shall provide an interface to configure whether or not a new
    39         -database image is capability of a new database image. 
           39  +database image is auto-vacuum capable.
           40  +
           41  +
           42  +
           43  +
           44  +HLR H51001
           45  +If successful, a call to the sqlite3BtreeOpen function shall return SQLITE_OK
           46  +and set the value of *ppBtree to contain a new B-Tree database connection
           47  +handle.
           48  +
           49  +HLR H51002
           50  +If unsuccessful, a call to the sqlite3BtreeOpen function shall return an SQLite
           51  +error code other than SQLITE_OK indicating the reason for the failure. The
           52  +value of *ppBtree shall not be modified in this case.
           53  +
           54  +HLR H51003
           55  +If the zFilename parameter to a call to sqlite3BtreeOpen is NULL or a pointer
           56  +to a buffer of which the first byte is a nul (0x00), then sqlite3BtreeOpen
           57  +shall attempt to open a connection to a temporary database.
           58  +
           59  +HLR H51004
           60  +If the zFilename parameter to a call to sqlite3BtreeOpen is a pointer to a
           61  +buffer containing a nul-terminated UTF-8 encoded string, sqlite3BtreeOpen shall
           62  +attempt to open a connection to a persistent database.
           63  +
           64  +HLR H51005
           65  +If the BTREE_OMIT_JOURNAL bit is set in the flags parameter passed to a 
           66  +successful call to sqlite3BtreeOpen to open a temporary database, then the
           67  +page-cache created as a result shall not open or use a journal file for any
           68  +purpose.
           69  +
           70  +HLR H51006
           71  +If the BTREE_NO_READLOCK bit is set in the flags parameter passed to a 
           72  +successful call to sqlite3BtreeOpen to open a persistent database and a
           73  +new page-cache is created as a result of the call, then the new page-cache 
           74  +shall only lock the database file-system representation when writing to
           75  +it.
           76  +
           77  +HLR H51007
           78  +If the sqlite3BtreeOpen function is called to open a connection to a persistent
           79  +database, and the call causes a new page-cache to be created, when opening the
           80  +database file using the VFS interface xOpen method the 4th parameter passed to
           81  +xOpen (flags) shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen.
           82  +
           83  +HLR H51008
           84  +If the sqlite3BtreeOpen function is called to open a connection to a temporary
           85  +database, if and when a temporary file is opened to use as secondary storage
           86  +using the VFS interface xOpen method the 4th parameter passed to xOpen (flags) 
           87  +shall be a copy of the vfsFlags value passed to sqlite3BtreeOpen with the 
           88  +SQLITE_OPEN_READWRITE, SQLITE_OPEN_CREATE, SQLITE_OPEN_EXCLUSIVE and 
           89  +SQLITE_OPEN_DELETEONCLOSE bits also set.
           90  +
           91  +HLR H51009
           92  +A call to the sqlite3BtreeClose function with a valid b-tree database
           93  +connection handle passed as the only argument shall invalidate the handle,
           94  +close the b-tree database connection and release all associated resources.
           95  +
           96  +HLR H51010
           97  +If a call to sqlite3BtreeClose is made to close a b-tree database connection
           98  +while there exist open B-Tree cursors that were opened using the specified
           99  +b-tree database connection, they shall be closed automatically from within
          100  +sqlite3BtreeClose, just as if their handles were passed to
          101  +sqlite3BtreeCloseCursor.
          102  +
          103  +
          104  +
          105  +
          106  +
          107  +
          108  +
    40    109