/ Check-in [14a9b945]
Login

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

Overview
Comment:Additional refinements to the new sqlite3_initialize() interface design. (CVS 5206)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 14a9b9453bc1c85785fcc44617af80912f5118c8
User & Date: drh 2008-06-12 00:07:29
Context
2008-06-12
02:16
Removed all C++ style comments. Ticket #3172. (CVS 5207) check-in: 59f72425 user: shane tags: trunk
00:07
Additional refinements to the new sqlite3_initialize() interface design. (CVS 5206) check-in: 14a9b945 user: drh tags: trunk
2008-06-11
18:56
Adjust the error-message text in corrupt7.test. (CVS 5205) check-in: 4a77ff5b user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    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
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.324 2008/06/10 17:41:45 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.325 2008/06/12 00:07:29 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
   841    841   #define SQLITE_ACCESS_EXISTS    0
   842    842   #define SQLITE_ACCESS_READWRITE 1
   843    843   #define SQLITE_ACCESS_READ      2
   844    844   
   845    845   /*
   846    846   ** CAPI3REF: Initialize The SQLite Library {F10130}
   847    847   **
   848         -** The sqlite3_initialize() routine does operating-system specific
   849         -** initialization of the SQLite library.  The sqlite3_shutdown()
   850         -** routine undoes the effect of sqlite3_initialize().  Typical tasks
   851         -** performed by these routines include allocation or deallocation
   852         -** of static resources, initialization of global variables,
   853         -** setting up a default [sqlite3_vfs | VFS] module, or setting up
   854         -** a default configuration using [sqlite3_config()].
          848  +** The sqlite3_initialize() routine initializes the
          849  +** SQLite library prior to use.  The sqlite3_shutdown() routine
          850  +** deallocates any resources that were allocated by sqlite3_initialize().
   855    851   **
   856         -** The sqlite3_initialize() routine can be called multiple times
          852  +** A call to sqlite3_initialize() is an "effective" call if it is
          853  +** the first time sqlite3_initialize() is invoked during the lifetime of
          854  +** the process, or if it is the first time sqlite3_initialize() is invoked
          855  +** following a call to sqlite3_shutdown().  Only an effective call
          856  +** of sqlite3_initialize() does any initialization.  All other calls
          857  +** are harmless no-ops.  In other words,
          858  +** the sqlite3_initialize() routine may be called multiple times
   857    859   ** without consequence.  Second and subsequent evaluations of
   858    860   ** sqlite3_initialize() are no-ops.  The sqlite3_initialize() routine
   859    861   ** only works the first time it is called for a process, or the first
   860    862   ** time it is called after sqlite3_shutdown().  In all other cases,
   861         -** sqlite3_initialize() returns SQLITE_OK.
          863  +** sqlite3_initialize() returns SQLITE_OK without doing any real work.
          864  +**
          865  +** Among other things, sqlite3_initialize() shall invoke
          866  +** [sqlite3_mutex_init()] and sqlite3_os_init().  Similarly, sqlite3_shutdown()
          867  +** shall invoke [sqlite3_mutex_end()] and sqlite3_os_end().
   862    868   **
   863    869   ** The sqlite3_initialize() routine returns SQLITE_OK on success.
   864    870   ** If for some reason, sqlite3_initialize() is unable to initialize
   865    871   ** the library (perhaps it is unable to allocate a needed resource such
   866    872   ** as a mutex) it returns an [error code] other than SQLITE_OK.
   867    873   **
   868    874   ** The sqlite3_initialize() routine is called internally by many other
   869         -** SQLite interfaces so that an application does not typically need to
          875  +** SQLite interfaces so that an application usually does not need to
   870    876   ** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
   871    877   ** calls sqlite3_initialize() so the SQLite library will be automatically
   872    878   ** initialized when [sqlite3_open()] is called if it has not be initialized
   873         -** already.
   874         -**
   875         -** Appropriate implementations for sqlite3_initialize() and sqlite3_shutdown()
   876         -** are provided as part of SQLite when it is compiled for unix, win32, and
   877         -** os/2.  However, when SQLite is compiled for other platforms, the
   878         -** implementations of sqlite3_initialize() and sqlite3_shutdown() are
   879         -** omitted and must be supplied by the application.
   880         -**
   881         -** The implementations of sqlite3_initialize() for unix, win32, and os/2
   882         -** are threadsafe and never fail.  However, the sqlite3_initialize()
   883         -** implementation for other operationing systems might not be threadsafe
   884         -** and so portable applications may want to invoke sqlite3_initialize()
   885         -** at application startup before other threads are created and check
   886         -** the return code to make sure that initialization was successful before
   887         -** continuing.  To restate: it is never necessary to call sqlite3_initialize()
   888         -** on unix, win32, or os/2, but making a serialized call to
   889         -** sqlite3_initialize() might be necessary on other operating systems.
   890         -**
   891         -** The sqlite3_shutdown() interface is not threadsafe on any platform and
   892         -** should be serialized by the application.  Few applications should ever
   893         -** need to call sqlite3_shutdown().  About the only reason for calling
   894         -** sqlite3_shutdown() is to deallocate static memory allocations to suppress
   895         -** spurious reports of memory leaks from program analysis tools.
          879  +** already.  However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT
          880  +** compile-time option, then the automatic calls to sqlite3_initialize()
          881  +** are omitted and the application must call sqlite3_initialize() directly
          882  +** prior to using any other SQLite interface.  For maximum portability,
          883  +** it is recommended that applications always invoke sqlite3_initialize()
          884  +** directly prior to using any other SQLite interface.  Future releases
          885  +** of SQLite may require this.  In other words, the behavior exhibited
          886  +** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the
          887  +** default behavior in some future release of SQLite.
          888  +**
          889  +** The sqlite3_os_init() routine does operating-system specific
          890  +** initialization of the SQLite library.  The sqlite3_os_end()
          891  +** routine undoes the effect of sqlite3_os_init().  Typical tasks
          892  +** performed by these routines include allocation or deallocation
          893  +** of static resources, initialization of global variables,
          894  +** setting up a default [sqlite3_vfs] module, or setting up
          895  +** a default configuration using [sqlite3_config()].  
          896  +**
          897  +** The application should never invoke either sqlite3_os_init()
          898  +** or sqlite3_os_end() directly.  The application should only invoke
          899  +** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
          900  +** interface is called automatically by sqlite3_initialize() and 
          901  +** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
          902  +** implementations for sqlite3_os_init() and sqlite3_os_end()
          903  +** are built into SQLite when it is compiled for unix, windows, or os/2.
          904  +** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time
          905  +** option) the application must supply a suitable implementation for
          906  +** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
          907  +** implementation of sqlite3_os_init() or sqlite3_os_end()
          908  +** must return SQLITE_OK on success and some other [error code] upon
          909  +** failure.
   896    910   */
   897    911   int sqlite3_initialize(void);
   898    912   int sqlite3_shutdown(void);
          913  +int sqlite3_os_init(void);
          914  +int sqlite3_os_end(void);
   899    915   
   900    916   /*
   901    917   ** CAPI3REF: Configuring The SQLite Library {F10145}
   902    918   **
   903    919   ** The sqlite3_config() interface is used to make global configuration
   904    920   ** changes to SQLite in order to tune SQLite to the specific needs of
   905    921   ** the application.  The default configuration is recommended for most
................................................................................
   957    973   ** to [database connections] and [prepared statements] so that the
   958    974   ** application is free to use the same [database connection] or the
   959    975   ** same [prepared statement] in different threads at the same time.</dd>
   960    976   **
   961    977   ** <dt>SQLITE_CONFIG_MALLOC</dt>
   962    978   ** <dd>This option takes four arguments.  The first three
   963    979   ** arguments are pointers to functions that emulate malloc(), free(),
   964         -** and realloc(), respectively.  The fourth argument is either a pointer to
   965         -** a function that returns the size of a prior allocation, or NULL.  If
   966         -** the fourth function is NULL, SQLite will keep track of allocation
   967         -** sizes itself.  This option is used to replace the default memory
          980  +** and realloc(), respectively.  The fourth argument must be a pointer to
          981  +** a function that returns the size of a prior allocation when handed a pointer
          982  +** to the allocation. This option is used to replace the default memory
   968    983   ** allocator with an application-defined memory allocator.</dd>
   969    984   **
   970    985   ** <dt>SQLITE_CONFIG_MEMSTATS</dt>
   971    986   ** <dd>This option takes single boolean argument which enables or disables
   972    987   ** the collection of memory allocation statistics.  When disabled, the
   973    988   ** following SQLite interfaces become non-operational:
   974    989   **   <ul>
................................................................................
  5619   5634   ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
  5620   5635   ** implementation is included with the library.  The
  5621   5636   ** mutex interface routines defined here become external
  5622   5637   ** references in the SQLite library for which implementations
  5623   5638   ** must be provided by the application.  This facility allows an
  5624   5639   ** application that links against SQLite to provide its own mutex
  5625   5640   ** implementation without having to modify the SQLite core.
         5641  +**
         5642  +** {F17001} The sqlite3_mutex_init() routine is called once by each
         5643  +** effective call to [sqlite3_initialize()].  The sqlite3_mutex_init()
         5644  +** interface initializes the mutex subsystem.  The application should
         5645  +** never call sqlite3_mutex_init() directly but only indirectly by
         5646  +** invoking [sqlite3_initialize()].
         5647  +**
         5648  +** {F17003} The sqlite3_mutex_end() routine undoes the effect of
         5649  +** sqlite3_mutex_init().  The sqlite3_mutex_end() interface is called
         5650  +** by [sqlite3_shutdown()].  The application should never call 
         5651  +** sqlite3_mutex_end() directly but only indirectly through
         5652  +** [sqlite3_shutdown()].
  5626   5653   **
  5627   5654   ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
  5628   5655   ** mutex and returns a pointer to it. {F17012} If it returns NULL
  5629   5656   ** that means that a mutex could not be allocated. {F17013} SQLite
  5630   5657   ** will unwind its stack and return an error. {F17014} The argument
  5631   5658   ** to sqlite3_mutex_alloc() is one of these integer constants:
  5632   5659   **
................................................................................
  5679   5706   ** upon successful entry.  {F17026} Mutexes created using
  5680   5707   ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
  5681   5708   ** {F17027} In such cases the,
  5682   5709   ** mutex must be exited an equal number of times before another thread
  5683   5710   ** can enter.  {U17028} If the same thread tries to enter any other
  5684   5711   ** kind of mutex more than once, the behavior is undefined.
  5685   5712   ** {F17029} SQLite will never exhibit
  5686         -** such behavior in its own use of mutexes. {END}
         5713  +** such behavior in its own use of mutexes.
  5687   5714   **
  5688         -** Some systems (ex: windows95) do not the operation implemented by
         5715  +** Some systems (ex: windows95) do not support the operation implemented by
  5689   5716   ** sqlite3_mutex_try().  On those systems, sqlite3_mutex_try() will
  5690   5717   ** always return SQLITE_BUSY.  {F17030} The SQLite core only ever uses
  5691         -** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
         5718  +** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
  5692   5719   **
  5693   5720   ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
  5694   5721   ** previously entered by the same thread.  {U17032} The behavior
  5695   5722   ** is undefined if the mutex is not currently entered by the
  5696   5723   ** calling thread or is not currently allocated.  {F17033} SQLite will
  5697   5724   ** never do either. {END}
  5698   5725   **
  5699   5726   ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
  5700   5727   */
         5728  +int sqlite3_mutex_init();
  5701   5729   sqlite3_mutex *sqlite3_mutex_alloc(int);
  5702   5730   void sqlite3_mutex_free(sqlite3_mutex*);
  5703   5731   void sqlite3_mutex_enter(sqlite3_mutex*);
  5704   5732   int sqlite3_mutex_try(sqlite3_mutex*);
  5705   5733   void sqlite3_mutex_leave(sqlite3_mutex*);
         5734  +int sqlite_mutex_end();
  5706   5735   
  5707   5736   /*
  5708   5737   ** CAPI3REF: Mutex Verifcation Routines {F17080}
  5709   5738   **
  5710   5739   ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
  5711   5740   ** are intended for use inside assert() statements. {F17081} The SQLite core
  5712   5741   ** never uses these routines except inside an assert() and applications

Changes to src/where.c.

    12     12   ** This module contains C code that generates VDBE code used to process
    13     13   ** the WHERE clause of SQL statements.  This module is responsible for
    14     14   ** generating the code that loops through a table looking for applicable
    15     15   ** rows.  Indices are selected and used to speed the search when doing
    16     16   ** so is applicable.  Because this module is responsible for selecting
    17     17   ** indices, you might also think of this module as the "query optimizer".
    18     18   **
    19         -** $Id: where.c,v 1.307 2008/05/30 14:58:37 drh Exp $
           19  +** $Id: where.c,v 1.308 2008/06/12 00:07:29 drh Exp $
    20     20   */
    21     21   #include "sqliteInt.h"
    22     22   
    23     23   /*
    24     24   ** The number of bits in a Bitmask.  "BMS" means "BitMask Size".
    25     25   */
    26     26   #define BMS  (sizeof(Bitmask)*8)
................................................................................
  2182   2182           bestFlags = flags;
  2183   2183           bestNEq = nEq;
  2184   2184           bestJ = j;
  2185   2185           pLevel->pBestIdx = pIndex;
  2186   2186         }
  2187   2187         if( doNotReorder ) break;
  2188   2188       }
  2189         -    WHERETRACE(("*** Optimizer choose table %d for loop %d\n", bestJ,
         2189  +    WHERETRACE(("*** Optimizer selects table %d for loop %d\n", bestJ,
  2190   2190              pLevel-pWInfo->a));
  2191   2191       if( (bestFlags & WHERE_ORDERBY)!=0 ){
  2192   2192         *ppOrderBy = 0;
  2193   2193       }
  2194   2194       andFlags &= bestFlags;
  2195   2195       pLevel->flags = bestFlags;
  2196   2196       pLevel->pIdx = pBest;