/ Check-in [32509bc7]
Login

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

Overview
Comment:More documentation and comment updates for sqlite3_initialize/shutdown interface changes to handle failures.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 32509bc7339cd6a46cea4c243e3418546860cb2d
User & Date: shane 2009-08-17 15:31:23
Context
2009-08-17
15:52
Move error simulation code from the sqlite3_os_init() functions into a wrapper. check-in: 67ad21ab user: dan tags: trunk
15:31
More documentation and comment updates for sqlite3_initialize/shutdown interface changes to handle failures. check-in: 32509bc7 user: shane tags: trunk
15:16
Add tests to check that sqlite recovers from an error in sqlite3_initialize() correctly. check-in: 904a371c user: dan tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Show Whitespace Changes Patch

configure became a regular file.

whitespace changes only

install-sh became a regular file.

whitespace changes only

Changes to src/mutex_unix.c.

    87     87   ** <li>  SQLITE_MUTEX_FAST
    88     88   ** <li>  SQLITE_MUTEX_RECURSIVE
    89     89   ** <li>  SQLITE_MUTEX_STATIC_MASTER
    90     90   ** <li>  SQLITE_MUTEX_STATIC_MEM
    91     91   ** <li>  SQLITE_MUTEX_STATIC_MEM2
    92     92   ** <li>  SQLITE_MUTEX_STATIC_PRNG
    93     93   ** <li>  SQLITE_MUTEX_STATIC_LRU
           94  +** <li>  SQLITE_MUTEX_STATIC_LRU2
    94     95   ** </ul>
    95     96   **
    96     97   ** The first two constants cause sqlite3_mutex_alloc() to create
    97     98   ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
    98     99   ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
    99    100   ** The mutex implementation does not need to make a distinction
   100    101   ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
   101    102   ** not want to.  But SQLite will only request a recursive mutex in
   102    103   ** cases where it really needs one.  If a faster non-recursive mutex
   103    104   ** implementation is available on the host platform, the mutex subsystem
   104    105   ** might return such a mutex in response to SQLITE_MUTEX_FAST.
   105    106   **
   106    107   ** The other allowed parameters to sqlite3_mutex_alloc() each return
   107         -** a pointer to a static preexisting mutex.  Three static mutexes are
          108  +** a pointer to a static preexisting mutex.  Six static mutexes are
   108    109   ** used by the current version of SQLite.  Future versions of SQLite
   109    110   ** may add additional static mutexes.  Static mutexes are for internal
   110    111   ** use by SQLite only.  Applications that use SQLite mutexes should
   111    112   ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
   112    113   ** SQLITE_MUTEX_RECURSIVE.
   113    114   **
   114    115   ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST

Changes to src/mutex_w32.c.

   127    127   ** The sqlite3_mutex_alloc() routine allocates a new
   128    128   ** mutex and returns a pointer to it.  If it returns NULL
   129    129   ** that means that a mutex could not be allocated.  SQLite
   130    130   ** will unwind its stack and return an error.  The argument
   131    131   ** to sqlite3_mutex_alloc() is one of these integer constants:
   132    132   **
   133    133   ** <ul>
   134         -** <li>  SQLITE_MUTEX_FAST               0
   135         -** <li>  SQLITE_MUTEX_RECURSIVE          1
   136         -** <li>  SQLITE_MUTEX_STATIC_MASTER      2
   137         -** <li>  SQLITE_MUTEX_STATIC_MEM         3
   138         -** <li>  SQLITE_MUTEX_STATIC_PRNG        4
          134  +** <li>  SQLITE_MUTEX_FAST
          135  +** <li>  SQLITE_MUTEX_RECURSIVE
          136  +** <li>  SQLITE_MUTEX_STATIC_MASTER
          137  +** <li>  SQLITE_MUTEX_STATIC_MEM
          138  +** <li>  SQLITE_MUTEX_STATIC_MEM2
          139  +** <li>  SQLITE_MUTEX_STATIC_PRNG
          140  +** <li>  SQLITE_MUTEX_STATIC_LRU
          141  +** <li>  SQLITE_MUTEX_STATIC_LRU2
   139    142   ** </ul>
   140    143   **
   141    144   ** The first two constants cause sqlite3_mutex_alloc() to create
   142    145   ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
   143    146   ** is used but not necessarily so when SQLITE_MUTEX_FAST is used.
   144    147   ** The mutex implementation does not need to make a distinction
   145    148   ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
   146    149   ** not want to.  But SQLite will only request a recursive mutex in
   147    150   ** cases where it really needs one.  If a faster non-recursive mutex
   148    151   ** implementation is available on the host platform, the mutex subsystem
   149    152   ** might return such a mutex in response to SQLITE_MUTEX_FAST.
   150    153   **
   151    154   ** The other allowed parameters to sqlite3_mutex_alloc() each return
   152         -** a pointer to a static preexisting mutex.  Three static mutexes are
          155  +** a pointer to a static preexisting mutex.  Six static mutexes are
   153    156   ** used by the current version of SQLite.  Future versions of SQLite
   154    157   ** may add additional static mutexes.  Static mutexes are for internal
   155    158   ** use by SQLite only.  Applications that use SQLite mutexes should
   156    159   ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
   157    160   ** SQLITE_MUTEX_RECURSIVE.
   158    161   **
   159    162   ** Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST

Changes to src/pcache1.c.

   408    408     }
   409    409     pcache1.isInit = 1;
   410    410     return SQLITE_OK;
   411    411   }
   412    412   
   413    413   /*
   414    414   ** Implementation of the sqlite3_pcache.xShutdown method.
          415  +** Note that the static mutex allocated in xInit does 
          416  +** not need to be freed.
   415    417   */
   416    418   static void pcache1Shutdown(void *NotUsed){
   417    419     UNUSED_PARAMETER(NotUsed);
   418    420     assert( pcache1.isInit!=0 );
   419    421     memset(&pcache1, 0, sizeof(pcache1));
   420    422   }
   421    423   

Changes to src/sqlite.h.in.

    14     14   ** or constant definition does not appear in this file, then it is
    15     15   ** not a published API of SQLite, is subject to change without
    16     16   ** notice, and should not be referenced by programs that use SQLite.
    17     17   **
    18     18   ** Some of the definitions that are in this file are marked as
    19     19   ** "experimental".  Experimental interfaces are normally new
    20     20   ** features recently added to SQLite.  We do not anticipate changes
    21         -** to experimental interfaces but reserve to make minor changes if
    22         -** experience from use "in the wild" suggest such changes are prudent.
           21  +** to experimental interfaces but reserve the right to make minor changes
           22  +** if experience from use "in the wild" suggest such changes are prudent.
    23     23   **
    24     24   ** The official C-language API documentation for SQLite is derived
    25     25   ** from comments in this file.  This file is the authoritative source
    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
................................................................................
    48     48   #ifndef SQLITE_EXTERN
    49     49   # define SQLITE_EXTERN extern
    50     50   #endif
    51     51   
    52     52   /*
    53     53   ** These no-op macros are used in front of interfaces to mark those
    54     54   ** interfaces as either deprecated or experimental.  New applications
    55         -** should not use deprecated intrfaces - they are support for backwards
           55  +** should not use deprecated interfaces - they are support for backwards
    56     56   ** compatibility only.  Application writers should be aware that
    57     57   ** experimental interfaces are subject to change in point releases.
    58     58   **
    59     59   ** These macros used to resolve to various kinds of compiler magic that
    60     60   ** would generate warning messages when they were used.  But that
    61     61   ** compiler magic ended up generating such a flurry of bug reports
    62     62   ** that we have taken it all out and gone back to using simple
................................................................................
   855    855   **
   856    856   ** The application should never invoke either sqlite3_os_init()
   857    857   ** or sqlite3_os_end() directly.  The application should only invoke
   858    858   ** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
   859    859   ** interface is called automatically by sqlite3_initialize() and
   860    860   ** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
   861    861   ** implementations for sqlite3_os_init() and sqlite3_os_end()
   862         -** are built into SQLite when it is compiled for unix, windows, or os/2.
          862  +** are built into SQLite when it is compiled for Unix, Windows, or OS/2.
   863    863   ** When built for other platforms (using the [SQLITE_OS_OTHER=1] compile-time
   864    864   ** option) the application must supply a suitable implementation for
   865    865   ** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
   866    866   ** implementation of sqlite3_os_init() or sqlite3_os_end()
   867    867   ** must return [SQLITE_OK] on success and some other [error code] upon
   868    868   ** failure.
   869    869   */
................................................................................
  1592   1592     char **pzErrmsg       /* Error msg written here */
  1593   1593   );
  1594   1594   void sqlite3_free_table(char **result);
  1595   1595   
  1596   1596   /*
  1597   1597   ** CAPI3REF: Formatted String Printing Functions {H17400} <S70000><S20000>
  1598   1598   **
  1599         -** These routines are workalikes of the "printf()" family of functions
         1599  +** These routines are work-alikes of the "printf()" family of functions
  1600   1600   ** from the standard C library.
  1601   1601   **
  1602   1602   ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  1603   1603   ** results into memory obtained from [sqlite3_malloc()].
  1604   1604   ** The strings returned by these two routines should be
  1605   1605   ** released by [sqlite3_free()].  Both routines return a
  1606   1606   ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
................................................................................
  1879   1879   **
  1880   1880   ** The authorizer callback must not do anything that will modify
  1881   1881   ** the database connection that invoked the authorizer callback.
  1882   1882   ** Note that [sqlite3_prepare_v2()] and [sqlite3_step()] both modify their
  1883   1883   ** database connections for the meaning of "modify" in this paragraph.
  1884   1884   **
  1885   1885   ** When [sqlite3_prepare_v2()] is used to prepare a statement, the
  1886         -** statement might be reprepared during [sqlite3_step()] due to a 
         1886  +** statement might be re-prepared during [sqlite3_step()] due to a 
  1887   1887   ** schema change.  Hence, the application should ensure that the
  1888   1888   ** correct authorizer callback remains in place during the [sqlite3_step()].
  1889   1889   **
  1890   1890   ** Note that the authorizer callback is invoked only during
  1891   1891   ** [sqlite3_prepare()] or its variants.  Authorization is not
  1892   1892   ** performed during statement evaluation in [sqlite3_step()], unless
  1893   1893   ** as stated in the previous paragraph, sqlite3_step() invokes
................................................................................
  4712   4712   ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
  4713   4713   ** not want to.  {H17016} But SQLite will only request a recursive mutex in
  4714   4714   ** cases where it really needs one.  {END} If a faster non-recursive mutex
  4715   4715   ** implementation is available on the host platform, the mutex subsystem
  4716   4716   ** might return such a mutex in response to SQLITE_MUTEX_FAST.
  4717   4717   **
  4718   4718   ** {H17017} The other allowed parameters to sqlite3_mutex_alloc() each return
  4719         -** a pointer to a static preexisting mutex. {END}  Four static mutexes are
         4719  +** a pointer to a static preexisting mutex. {END}  Six static mutexes are
  4720   4720   ** used by the current version of SQLite.  Future versions of SQLite
  4721   4721   ** may add additional static mutexes.  Static mutexes are for internal
  4722   4722   ** use by SQLite only.  Applications that use SQLite mutexes should
  4723   4723   ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
  4724   4724   ** SQLITE_MUTEX_RECURSIVE.
  4725   4725   **
  4726   4726   ** {H17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
................................................................................
  5204   5204   /*
  5205   5205   ** CAPI3REF: Application Defined Page Cache.
  5206   5206   ** EXPERIMENTAL
  5207   5207   **
  5208   5208   ** The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
  5209   5209   ** register an alternative page cache implementation by passing in an 
  5210   5210   ** instance of the sqlite3_pcache_methods structure. The majority of the 
  5211         -** heap memory used by sqlite is used by the page cache to cache data read 
         5211  +** heap memory used by SQLite is used by the page cache to cache data read 
  5212   5212   ** from, or ready to be written to, the database file. By implementing a 
  5213   5213   ** custom page cache using this API, an application can control more 
  5214         -** precisely the amount of memory consumed by sqlite, the way in which 
         5214  +** precisely the amount of memory consumed by SQLite, the way in which 
  5215   5215   ** said memory is allocated and released, and the policies used to 
  5216   5216   ** determine exactly which parts of a database file are cached and for 
  5217   5217   ** how long.
  5218   5218   **
  5219         -** The contents of the structure are copied to an internal buffer by sqlite
         5219  +** The contents of the structure are copied to an internal buffer by SQLite
  5220   5220   ** within the call to [sqlite3_config].
  5221   5221   **
  5222   5222   ** The xInit() method is called once for each call to [sqlite3_initialize()]
  5223   5223   ** (usually only once during the lifetime of the process). It is passed
  5224   5224   ** a copy of the sqlite3_pcache_methods.pArg value. It can be used to set
  5225   5225   ** up global structures and mutexes required by the custom page cache 
  5226         -** implementation. The xShutdown() method is called from within 
  5227         -** [sqlite3_shutdown()], if the application invokes this API. It can be used
  5228         -** to clean up any outstanding resources before process shutdown, if required.
         5226  +** implementation. 
         5227  +**
         5228  +** The xShutdown() method is called from within [sqlite3_shutdown()], 
         5229  +** if the application invokes this API. It can be used to clean up 
         5230  +** any outstanding resources before process shutdown, if required.
         5231  +**
         5232  +** SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
         5233  +** the xInit method, so the xInit method need not be threadsafe.  The
         5234  +** xShutdown method is only called from [sqlite3_shutdown()] so it does
         5235  +** not need to be threadsafe either.  All other methods must be threadsafe
         5236  +** in multithreaded applications.
         5237  +**
         5238  +** SQLite will never invoke xInit() more than once without an intervening
         5239  +** call to xShutdown().
  5229   5240   **
  5230   5241   ** The xCreate() method is used to construct a new cache instance. The
  5231   5242   ** first parameter, szPage, is the size in bytes of the pages that must
  5232   5243   ** be allocated by the cache. szPage will not be a power of two. The
  5233   5244   ** second argument, bPurgeable, is true if the cache being created will
  5234   5245   ** be used to cache database pages read from a file stored on disk, or
  5235   5246   ** false if it is used for an in-memory database. The cache implementation

test/progress.test became a regular file.

whitespace changes only

tool/mkopts.tcl became a regular file.

whitespace changes only