/ Check-in [ca92c024]
Login

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

Overview
Comment:Improved documentation for checkpoints and the busy handler. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: ca92c0240681b199c4b8ecc557792b8aea71692d
User & Date: drh 2014-07-18 19:06:39
Context
2014-07-18
21:02
Update clean targets with the recently added command-line tools. check-in: 2beefa68 user: mistachkin tags: trunk
19:06
Improved documentation for checkpoints and the busy handler. No changes to code. check-in: ca92c024 user: drh tags: trunk
17:39
SQLite has long accepted some unadvertised and non-standard join syntax. Add a test to ensure that future versions continue to accept this non-standard syntax, to avoid breaking legacy applications that use the undefined syntax. check-in: 824dde7f user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  2028   2028   */
  2029   2029   int sqlite3_complete(const char *sql);
  2030   2030   int sqlite3_complete16(const void *sql);
  2031   2031   
  2032   2032   /*
  2033   2033   ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors
  2034   2034   **
  2035         -** ^This routine sets a callback function that might be invoked whenever
  2036         -** an attempt is made to open a database table that another thread
  2037         -** or process has locked.
         2035  +** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X
         2036  +** that might be invoked with argument P whenever
         2037  +** an attempt is made to access a database table associated with
         2038  +** [database connection] D when another thread
         2039  +** or process has the table locked.
         2040  +** The sqlite3_busy_handler() interface is used to implement
         2041  +** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout].
  2038   2042   **
  2039   2043   ** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED]
  2040   2044   ** is returned immediately upon encountering the lock.  ^If the busy callback
  2041   2045   ** is not NULL, then the callback might be invoked with two arguments.
  2042   2046   **
  2043   2047   ** ^The first argument to the busy handler is a copy of the void* pointer which
  2044   2048   ** is the third argument to sqlite3_busy_handler().  ^The second argument to
  2045   2049   ** the busy handler callback is the number of times that the busy handler has
  2046         -** been invoked for this locking event.  ^If the
         2050  +** been invoked for the same locking event.  ^If the
  2047   2051   ** busy callback returns 0, then no additional attempts are made to
  2048         -** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned.
         2052  +** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned
         2053  +** to the application.
  2049   2054   ** ^If the callback returns non-zero, then another attempt
  2050         -** is made to open the database for reading and the cycle repeats.
         2055  +** is made to access the database and the cycle repeats.
  2051   2056   **
  2052   2057   ** The presence of a busy handler does not guarantee that it will be invoked
  2053   2058   ** when there is lock contention. ^If SQLite determines that invoking the busy
  2054   2059   ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY]
  2055         -** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler.
         2060  +** or [SQLITE_IOERR_BLOCKED] to the application instead of invoking the 
         2061  +** busy handler.
  2056   2062   ** Consider a scenario where one process is holding a read lock that
  2057   2063   ** it is trying to promote to a reserved lock and
  2058   2064   ** a second process is holding a reserved lock that it is trying
  2059   2065   ** to promote to an exclusive lock.  The first process cannot proceed
  2060   2066   ** because it is blocked by the second and the second process cannot
  2061   2067   ** proceed because it is blocked by the first.  If both processes
  2062   2068   ** invoke the busy handlers, neither will make any progress.  Therefore,
................................................................................
  2080   2086   ** <a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">
  2081   2087   ** CorruptionFollowingBusyError</a> wiki page for a discussion of why
  2082   2088   ** this is important.
  2083   2089   **
  2084   2090   ** ^(There can only be a single busy handler defined for each
  2085   2091   ** [database connection].  Setting a new busy handler clears any
  2086   2092   ** previously set handler.)^  ^Note that calling [sqlite3_busy_timeout()]
  2087         -** will also set or clear the busy handler.
         2093  +** or evaluating [PRAGMA busy_timeout=N] will change the
         2094  +** busy handler and thus clear any previously set busy handler.
  2088   2095   **
  2089   2096   ** The busy callback should not take any actions which modify the
  2090         -** database connection that invoked the busy handler.  Any such actions
         2097  +** database connection that invoked the busy handler.  In other words,
         2098  +** the busy handler is not reentrant.  Any such actions
  2091   2099   ** result in undefined behavior.
  2092   2100   ** 
  2093   2101   ** A busy handler must not close the database connection
  2094   2102   ** or [prepared statement] that invoked the busy handler.
  2095   2103   */
  2096   2104   int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);
  2097   2105   
................................................................................
  2108   2116   ** ^Calling this routine with an argument less than or equal to zero
  2109   2117   ** turns off all busy handlers.
  2110   2118   **
  2111   2119   ** ^(There can only be a single busy handler for a particular
  2112   2120   ** [database connection] any any given moment.  If another busy handler
  2113   2121   ** was defined  (using [sqlite3_busy_handler()]) prior to calling
  2114   2122   ** this routine, that other busy handler is cleared.)^
         2123  +**
         2124  +** See also:  [PRAGMA busy_timeout]
  2115   2125   */
  2116   2126   int sqlite3_busy_timeout(sqlite3*, int ms);
  2117   2127   
  2118   2128   /*
  2119   2129   ** CAPI3REF: Convenience Routines For Running Queries
  2120   2130   **
  2121   2131   ** This is a legacy interface that is preserved for backwards compatibility.
................................................................................
  7134   7144   ** ^The callback registered by this function replaces any existing callback
  7135   7145   ** registered using [sqlite3_wal_hook()].  ^Likewise, registering a callback
  7136   7146   ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism
  7137   7147   ** configured by this function.
  7138   7148   **
  7139   7149   ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface
  7140   7150   ** from SQL.
         7151  +**
         7152  +** ^Checkpoints initiated by this mechanism are
         7153  +** [sqlite3_wal_checkpoint_v2|PASSIVE].
  7141   7154   **
  7142   7155   ** ^Every new [database connection] defaults to having the auto-checkpoint
  7143   7156   ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT]
  7144   7157   ** pages.  The use of this interface
  7145   7158   ** is only necessary if the default setting is found to be suboptimal
  7146   7159   ** for a particular application.
  7147   7160   */
................................................................................
  7151   7164   ** CAPI3REF: Checkpoint a database
  7152   7165   **
  7153   7166   ** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X
  7154   7167   ** on [database connection] D to be [checkpointed].  ^If X is NULL or an
  7155   7168   ** empty string, then a checkpoint is run on all databases of
  7156   7169   ** connection D.  ^If the database connection D is not in
  7157   7170   ** [WAL | write-ahead log mode] then this interface is a harmless no-op.
         7171  +** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a
         7172  +** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint.
         7173  +** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL
         7174  +** or RESET checkpoint.
  7158   7175   **
  7159   7176   ** ^The [wal_checkpoint pragma] can be used to invoke this interface
  7160   7177   ** from SQL.  ^The [sqlite3_wal_autocheckpoint()] interface and the
  7161   7178   ** [wal_autocheckpoint pragma] can be used to cause this interface to be
  7162   7179   ** run whenever the WAL reaches a certain size threshold.
  7163   7180   **
  7164   7181   ** See also: [sqlite3_wal_checkpoint_v2()]
................................................................................
  7173   7190   ** eMode parameter:
  7174   7191   **
  7175   7192   ** <dl>
  7176   7193   ** <dt>SQLITE_CHECKPOINT_PASSIVE<dd>
  7177   7194   **   Checkpoint as many frames as possible without waiting for any database 
  7178   7195   **   readers or writers to finish. Sync the db file if all frames in the log
  7179   7196   **   are checkpointed. This mode is the same as calling 
  7180         -**   sqlite3_wal_checkpoint(). The busy-handler callback is never invoked.
         7197  +**   sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback]
         7198  +**   is never invoked.
  7181   7199   **
  7182   7200   ** <dt>SQLITE_CHECKPOINT_FULL<dd>
  7183         -**   This mode blocks (calls the busy-handler callback) until there is no
         7201  +**   This mode blocks (it invokes the
         7202  +**   [sqlite3_busy_handler|busy-handler callback]) until there is no
  7184   7203   **   database writer and all readers are reading from the most recent database
  7185   7204   **   snapshot. It then checkpoints all frames in the log file and syncs the
  7186   7205   **   database file. This call blocks database writers while it is running,
  7187   7206   **   but not database readers.
  7188   7207   **
  7189   7208   ** <dt>SQLITE_CHECKPOINT_RESTART<dd>
  7190   7209   **   This mode works the same way as SQLITE_CHECKPOINT_FULL, except after 
  7191         -**   checkpointing the log file it blocks (calls the busy-handler callback)
         7210  +**   checkpointing the log file it blocks (calls the 
         7211  +**   [sqlite3_busy_handler|busy-handler callback])
  7192   7212   **   until all readers are reading from the database file only. This ensures 
  7193   7213   **   that the next client to write to the database file restarts the log file 
  7194   7214   **   from the beginning. This call blocks database writers while it is running,
  7195   7215   **   but not database readers.
  7196   7216   ** </dl>
  7197   7217   **
  7198   7218   ** If pnLog is not NULL, then *pnLog is set to the total number of frames in