Documentation Source Text

Check-in [a4e2a17a94]
Login

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

Overview
Comment:Add LLR to do with the advisory b-tree locks used in shared-cache mode.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:a4e2a17a9432f6e9c9f3cf4e17c0ca443abe77d7
User & Date: dan 2009-07-02 00:26:31
Context
2009-07-03
15:38
Enhance the CREATE TRIGGER documentation to describe restrictions on INSERT, UPDATE, and DELETE statements that occur within triggers. CVS Ticket #3947. check-in: b7dfcf7883 user: drh tags: trunk
2009-07-02
00:26
Add LLR to do with the advisory b-tree locks used in shared-cache mode. check-in: a4e2a17a94 user: dan tags: trunk
2009-06-27
14:07
Preparing for the 3.6.16 release. check-in: 5eeec98501 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to pages/btreemodule.in.

   517    517         with the open database.
   518    518   
   519    519         [fancyformat_import_requirement H50131]
   520    520         [fancyformat_import_requirement H50129]
   521    521         [fancyformat_import_requirement H50130]
   522    522   
   523    523       [h3 "Multi-User Database Requirements"]
          524  +
          525  +      [fancyformat_import_requirement H50156]
          526  +
   524    527     <ul>
   525    528       <li> Lock on schema memory object.
   526    529       <li> Locks on b-tree tables.
   527    530       <li> "Unlock notify" feature.
   528    531       <li> Mutexes/thread-safety features.
   529    532     </ul>
   530    533   
................................................................................
   549    552       [h3 "Caching and Memory Management Requirements" hlr_memory]
   550    553     <ul>
   551    554       <li> Memory allocation related features (pcache, scratch memory, other...).
   552    555       <li> Default pcache implementation (sqlite3_release_memory()).
   553    556       <li> Schema memory object allocation (destructor registration).
   554    557     </ul>
   555    558   
   556         -    [h3 "Fault Tolerance Requirements"]
          559  +    [h3 "Exception Handling Requirements"]
          560  +
          561  +  <p>
          562  +    System failure. Do not corrupt the database image.
          563  +  <p>
          564  +    Three kinds of exception:
   557    565     <ul>
   558         -    <li> Don't corrupt the database. Various modes and the expectations of them.
          566  +    <li> IO Error.
          567  +    <li> Malloc request failure.
          568  +    <li> Database image corruption.
   559    569     </ul>
   560    570   
   561    571       [h3 "Well-Formedness Requirements"]
   562    572     <ul>
   563    573       <li> Identify the subset of file-format well-formedness requirements that
   564    574            this module is responsible for implementing.
   565    575       <li> Define how the module should respond to corrupt database files: don't
................................................................................
   798    808         <p>
   799    809   	The sqlite3BtreeGetMeta interface may be used to retrieve the current
   800    810           value of certain fields from the database image header.
   801    811   
   802    812         [btree_api_defn sqlite3BtreeGetMeta]
   803    813   
   804    814         [fancyformat_import_requirement H51015]
          815  +      [fancyformat_import_requirement H51016]
          816  +
          817  +      <p>
          818  +        The two requirements above imply that if sqlite3BtreeGetMeta is called with
          819  +        anything other than a b-tree database connection handle with an open read-only
          820  +        or read-write transaction as the first argument, or with anything other than
          821  +        an integer between 0 and 7 (inclusive) as the second, the results are undefined.
   805    822   
   806    823         [btree_api_defn BTREE_FREE_PAGE_COUNT BTREE_SCHEMA_VERSION BTREE_FILE_FORMAT \
   807    824                         BTREE_DEFAULT_CACHE_SIZE BTREE_LARGEST_ROOT_PAGE BTREE_TEXT_ENCODING \
   808    825                         BTREE_USER_VERSION BTREE_INCR_VACUUM]
   809    826   
   810         -      [fancyformat_import_requirement H51016]
          827  +      [fancyformat_import_requirement H51017]
   811    828   
   812    829   
   813    830   
   814    831   
   815    832       [h2 "Modifying the Database Image"]
   816    833   
   817    834         [h3 sqlite3BtreeCreateTable sqlite3BtreeCreateTable]
................................................................................
   891    908           Malloc and IO error handling. Maybe these should be grouped together
   892    909           for a whole bunch of APIs. And hook into the above via a defintion of
   893    910           "successful call".
   894    911   
   895    912         [h3 sqlite3BtreeIncrVacuum sqlite3BtreeIncrVacuum]
   896    913         [btree_api_defn sqlite3BtreeIncrVacuum]
   897    914   
          915  +    [h2 "Advisory B-Tree Locks"] 
          916  +
          917  +      <p>
          918  +	This section describes the b-tree module interfaces used for acquiring
          919  +	and querying the advisory locks that can be placed on database image
          920  +	pages. The locking mechanisms described in this section are only used
          921  +	to arbitrate between multiple clients of the same in-memory page-cache.
          922  +	The locking mechanism used to control access to a file-system
          923  +	representation of the database when multiple in-memory page caches
          924  +	(possibly located in different OS processes) are open on it is
          925  +        described in <span class=todo>this</span>.
          926  +
          927  +      <p>
          928  +        As well as obtaining advisory locks explicitly using the 
          929  +        sqlite3BtreeLockTable API (see below), a read-lock on page 1 of the
          930  +        database image is automatically obtained whenever a b-tree database 
          931  +	connection opens a read-only or read-write transaction (see 
          932  +        <span class=todo>requirement number</span>). Note that this means
          933  +        that a write-lock on page 1 is effectively an exclusive lock on
          934  +	the entire page-cache, as it prevents any other connection from opening
          935  +        a transaction of any kind.
          936  +
          937  +      [h3 sqlite3BtreeLockTable]
          938  +
          939  +      [btree_api_defn sqlite3BtreeLockTable]
          940  +
          941  +      <p>
          942  +        The sqlite3BtreeLockTable API allows database clients to place 
          943  +        advisory read or write locks on a specified page of the database 
          944  +        image. The specified page need not exist within the database image.
          945  +        By convention, SQLite acquires read and write locks on the root
          946  +        pages of table b-trees only, but this is not required to be enforced
          947  +        by the b-tree module. Locks may only be obtained when a database
          948  +        client has an open transaction. All locks are automatically released
          949  +        when the open transaction is concluded.
          950  +
          951  +        [fancyformat_import_requirement L50016]
          952  +        [fancyformat_import_requirement L50017]
          953  +
          954  +      <p>
          955  +        The two requirements above imply that the results of calling 
          956  +        sqlite3BtreeLockTable on a b-tree database connection handle that does
          957  +        not currently have an open transaction, or attempting to obtain
          958  +        a write-lock using a b-tree database connection handle that only has
          959  +        a read-only transaction open are undefined.
          960  +
          961  +
          962  +        [fancyformat_import_requirement L50019]
          963  +        [fancyformat_import_requirement L50020]
          964  +
          965  +      <p>
          966  +        Requirement L50020 is overly conservative. Because a write-lock may 
          967  +        only be requested if the b-tree database connection has an open read-write 
          968  +	transaction (L50017), and at most a single b-tree database connection
          969  +        may have such an open transaction at one time, it is not possible for
          970  +        a request for a write-lock to fail because another connection is holding
          971  +        a write-lock on the same b-tree database image page. It may, however,
          972  +        fail because another connection is holding a read-lock.
          973  +
          974  +      <p>
          975  +        All locks are held until the current transaction is concluded.
          976  +
          977  +        [fancyformat_import_requirement L50018]
          978  +
          979  +      <p class=todo> Malloc failure?
          980  +
          981  +      <p class=todo> Read uncommitted flag. Maybe this should be handled
          982  +        outside of the b-tree module. Is there anything to stop connections
          983  +        with this flag set simply not obtaining read locks? There are assert()
          984  +        statements in the b-tree module that need to take this flag into account,
          985  +        but not actual functionality.
          986  +
          987  +      [h3 sqlite3BtreeSchemaLocked]
          988  +      [btree_api_defn sqlite3BtreeSchemaLocked]
          989  +
          990  +        [fancyformat_import_requirement L50014]
          991  +        [fancyformat_import_requirement L50015]
          992  +
   898    993       [h2 "What do these do?"]
   899    994   
   900    995       <p class=todo>
   901    996         The following is used only from within VdbeExec() to check whether or not
   902    997         a cursor was opened on a table or index b-tree. Corruption tests can move into
   903    998         the b-tree layer.
   904    999   

Changes to req/hlr50000.txt.

   302    302   the safety-level of a page-cache to one of "off", "normal" or "full",
   303    303   given an open b-tree database connection to that page-cache.
   304    304   
   305    305   HLR H50155
   306    306   The default value assigned to the safety-level configuration parameter of a
   307    307   page-cache shall be "full".
   308    308   
          309  +HLR H50156
          310  +The b-tree module shall provide an interface allowing database clients to
          311  +acquire advisory read (shared) or write (exclusive) locks on a specific b-tree
          312  +structure within the database.
          313  +
   309    314   
   310    315   
   311    316   HLR H51001      H50010
   312    317   If successful, a call to the sqlite3BtreeOpen function shall return SQLITE_OK
   313    318   and set the value of *ppBtree to contain a new B-Tree database connection
   314    319   handle.
   315    320   
................................................................................
   392    397   HLR H51014
   393    398   A call to the sqlite3BtreeGetJournalname function with a valid B-Tree database
   394    399   connection handle opened on a temporary database as the first argument shall
   395    400   return a pointer to a buffer to a nul-terminated string zero bytes in length
   396    401   (i.e. the first byte of the buffer shall be 0x00).
   397    402   
   398    403   
          404  +
   399    405   
   400    406   HLR H51015       H50109
   401         -If successful, a call to the sqlite3BtreeGetMeta function shall set the
   402         -value of *pValue to the current value of the specified 32-bit unsigned 
   403         -integer in the database image database header and return SQLITE_OK.
          407  +If the first parameter is a b-tree database connection handle with an open
          408  +read-only or read-write transaction, and the second parameter is an integer
          409  +between 0 and 7 inclusive, and the database image consists of zero pages,
          410  +a call to the sqlite3BtreeGetMeta function shall set the value of *pValue to 
          411  +zero.
   404    412   
   405    413   HLR H51016       H50109
   406         -The database header field read from the database image by a call to
   407         -sqlite3BtreeGetMeta shall be the 32-bit unsigned integer header field stored at
   408         -byte offset (36 + 4 * idx) of the database header, where idx is the value of
   409         -the second parameter passed to sqlite3BtreeGetMeta.
          414  +If the first parameter is a b-tree database connection handle with an open
          415  +read-only or read-write transaction, and the second parameter is an integer
          416  +between 0 and 7 inclusive, and the database image consists of one or more
          417  +pages, a call to the sqlite3BtreeGetMeta function shall set the value of
          418  +*pValue to the current value of the specified 32-bit unsigned integer in the
          419  +database image database header.
   410    420   
          421  +HLR H51017       H50109
          422  +The database header field read from the database image by a call to
          423  +sqlite3BtreeGetMeta in the situation specified by H51016 shall be the 32-bit 
          424  +unsigned integer header field stored at byte offset (36 + 4 * idx) of the
          425  +database header, where idx is the value of the second parameter passed to
          426  +sqlite3BtreeGetMeta.
   411    427   

Changes to req/llr50000.txt.

    73     73   pointing to an entry with a smaller key than that requested, or the cursor
    74     74   is left pointing a no entry at all because the b-tree structure is completely
    75     75   empty, *pRes (the value of the "int" variable pointed to by the pointer passed
    76     76   as the fifth parameter to sqlite3BtreeMovetoUnpacked) shall be set to -1.
    77     77   Otherwise, if the b-tree cursor is left pointing to an entry with a larger key
    78     78   than that requested, *pRes shall be set to 1.
    79     79   
    80         -
    81     80   HLR L50013  H50127
    82     81   A successful call to the sqlite3BtreeDelete function made with a read/write
    83     82   b-tree cursor passed as the first argument shall remove the entry pointed to by
    84     83   the b-tree cursor from the b-tree structure. 
           84  +
           85  +
           86  +
           87  +HLR L50014
           88  +A call to the sqlite3BtreeSchemaLocked function with a valid b-tree 
           89  +database connection as the only argument shall return SQLITE_LOCKED_SHAREDCACHE
           90  +if there exists another b-tree database connection connected to the
           91  +same page-cache that currently holds a write-lock on database image
           92  +page 1.
           93  +
           94  +HLR L50015
           95  +A call to the sqlite3BtreeSchemaLocked function with a valid b-tree 
           96  +database connection as the only argument shall return SQLITE_OK if
           97  +H51017 does not apply.
           98  +
           99  +HLR L50016
          100  +A call to sqlite3BtreeLockTable, specifying a b-tree database connection handle 
          101  +with an open read-only or read-write transaction as the first parameter, and 
          102  +zero as the third parameter, shall attempt to obtain a read-lock on the database
          103  +page specified by the second parameter.
          104  +
          105  +HLR L50017
          106  +A call to sqlite3BtreeLockTable, specifying a b-tree database connection handle 
          107  +with an open read-write transaction as the first parameter, and a non-zero value as 
          108  +the third parameter, shall attempt to obtain a write-lock on the database
          109  +page specified by the second parameter.
          110  +
          111  +HLR L50018
          112  +When a read-only or read-write transaction is concluded, all advisory b-tree locks
          113  +held by the b-tree database connection shall be relinquished.
          114  +
          115  +HLR L50019
          116  +If, when attempting to obtain a read-lock as described in L50016, there exists
          117  +another b-tree database connection connected to the same page-cache that is
          118  +holding a write-lock on the same database image page, the read-lock shall not
          119  +be granted and the call to sqlite3BtreeLockTable shall return SQLITE_LOCKED_SHAREDCACHE.
          120  +
          121  +HLR L50020
          122  +If, when attempting to obtain a write-lock as described in L50017, there exists
          123  +another b-tree database connection connected to the same page-cache that is
          124  +holding a read or write-lock on the same database image page, the write-lock 
          125  +shall not be granted and the call to sqlite3BtreeLockTable shall return 
          126  +SQLITE_LOCKED_SHAREDCACHE.
          127  +
    85    128   
    86    129   
    87    130   
    88    131   HLR L51001
    89    132   The balance-siblings algorithm shall redistribute the b-tree cells currently 
    90    133   stored on a overfull or underfull page and up to two sibling pages, adding
    91    134   or removing siblings as required, such that no sibling page is overfull and
    92    135   the minimum possible number of sibling pages is used to store the 
    93    136   redistributed b-tree cells.
    94    137