SQLite

Check-in [14a9b9453b]
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
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 14a9b9453bc1c85785fcc44617af80912f5118c8
User & Date: drh 2008-06-12 00:07:29.000
Context
2008-06-12
02:16
Removed all C++ style comments. Ticket #3172. (CVS 5207) (check-in: 59f72425eb user: shane tags: trunk)
00:07
Additional refinements to the new sqlite3_initialize() interface design. (CVS 5206) (check-in: 14a9b9453b user: drh tags: trunk)
2008-06-11
18:56
Adjust the error-message text in corrupt7.test. (CVS 5205) (check-in: 4a77ff5b58 user: drh tags: trunk)
Changes
Unified Diff Show Whitespace Changes Patch
Changes to src/sqlite.h.in.
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.324 2008/06/10 17:41:45 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.







|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.325 2008/06/12 00:07:29 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855






856
857
858
859
860
861




862
863
864
865
866
867
868
869
870
871
872
873
874
875



876
877
878
879

880
881
882
883
884
885

886
887
888
889
890



891




892
893
894
895


896
897
898


899
900
901
902
903
904
905
#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1
#define SQLITE_ACCESS_READ      2

/*
** CAPI3REF: Initialize The SQLite Library {F10130}
**
** The sqlite3_initialize() routine does operating-system specific
** initialization of the SQLite library.  The sqlite3_shutdown()
** routine undoes the effect of sqlite3_initialize().  Typical tasks
** performed by these routines include allocation or deallocation
** of static resources, initialization of global variables,
** setting up a default [sqlite3_vfs | VFS] module, or setting up
** a default configuration using [sqlite3_config()].
**






** The sqlite3_initialize() routine can be called multiple times
** without consequence.  Second and subsequent evaluations of
** sqlite3_initialize() are no-ops.  The sqlite3_initialize() routine
** only works the first time it is called for a process, or the first
** time it is called after sqlite3_shutdown().  In all other cases,
** sqlite3_initialize() returns SQLITE_OK.




**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** If for some reason, sqlite3_initialize() is unable to initialize
** the library (perhaps it is unable to allocate a needed resource such
** as a mutex) it returns an [error code] other than SQLITE_OK.
**
** The sqlite3_initialize() routine is called internally by many other
** SQLite interfaces so that an application does not typically need to
** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
** calls sqlite3_initialize() so the SQLite library will be automatically
** initialized when [sqlite3_open()] is called if it has not be initialized
** already.
**
** Appropriate implementations for sqlite3_initialize() and sqlite3_shutdown()



** are provided as part of SQLite when it is compiled for unix, win32, and
** os/2.  However, when SQLite is compiled for other platforms, the
** implementations of sqlite3_initialize() and sqlite3_shutdown() are
** omitted and must be supplied by the application.

**
** The implementations of sqlite3_initialize() for unix, win32, and os/2
** are threadsafe and never fail.  However, the sqlite3_initialize()
** implementation for other operationing systems might not be threadsafe
** and so portable applications may want to invoke sqlite3_initialize()
** at application startup before other threads are created and check

** the return code to make sure that initialization was successful before
** continuing.  To restate: it is never necessary to call sqlite3_initialize()
** on unix, win32, or os/2, but making a serialized call to
** sqlite3_initialize() might be necessary on other operating systems.
**



** The sqlite3_shutdown() interface is not threadsafe on any platform and




** should be serialized by the application.  Few applications should ever
** need to call sqlite3_shutdown().  About the only reason for calling
** sqlite3_shutdown() is to deallocate static memory allocations to suppress
** spurious reports of memory leaks from program analysis tools.


*/
int sqlite3_initialize(void);
int sqlite3_shutdown(void);



/*
** CAPI3REF: Configuring The SQLite Library {F10145}
**
** The sqlite3_config() interface is used to make global configuration
** changes to SQLite in order to tune SQLite to the specific needs of
** the application.  The default configuration is recommended for most







|
|
|
<
<
<
<

>
>
>
>
>
>
|




|
>
>
>
>







|



|
|
|
>
>
>
|
|
<
<
>

|
|
<
|
<
>
|
|
<
|

>
>
>
|
>
>
>
>
|
|
|
<
>
>



>
>







841
842
843
844
845
846
847
848
849
850




851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886


887
888
889
890

891

892
893
894

895
896
897
898
899
900
901
902
903
904
905
906
907

908
909
910
911
912
913
914
915
916
917
918
919
920
921
#define SQLITE_ACCESS_EXISTS    0
#define SQLITE_ACCESS_READWRITE 1
#define SQLITE_ACCESS_READ      2

/*
** CAPI3REF: Initialize The SQLite Library {F10130}
**
** The sqlite3_initialize() routine initializes the
** SQLite library prior to use.  The sqlite3_shutdown() routine
** deallocates any resources that were allocated by sqlite3_initialize().




**
** A call to sqlite3_initialize() is an "effective" call if it is
** the first time sqlite3_initialize() is invoked during the lifetime of
** the process, or if it is the first time sqlite3_initialize() is invoked
** following a call to sqlite3_shutdown().  Only an effective call
** of sqlite3_initialize() does any initialization.  All other calls
** are harmless no-ops.  In other words,
** the sqlite3_initialize() routine may be called multiple times
** without consequence.  Second and subsequent evaluations of
** sqlite3_initialize() are no-ops.  The sqlite3_initialize() routine
** only works the first time it is called for a process, or the first
** time it is called after sqlite3_shutdown().  In all other cases,
** sqlite3_initialize() returns SQLITE_OK without doing any real work.
**
** Among other things, sqlite3_initialize() shall invoke
** [sqlite3_mutex_init()] and sqlite3_os_init().  Similarly, sqlite3_shutdown()
** shall invoke [sqlite3_mutex_end()] and sqlite3_os_end().
**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** If for some reason, sqlite3_initialize() is unable to initialize
** the library (perhaps it is unable to allocate a needed resource such
** as a mutex) it returns an [error code] other than SQLITE_OK.
**
** The sqlite3_initialize() routine is called internally by many other
** SQLite interfaces so that an application usually does not need to
** invoke sqlite3_initialize() directly.  For example, [sqlite3_open()]
** calls sqlite3_initialize() so the SQLite library will be automatically
** initialized when [sqlite3_open()] is called if it has not be initialized
** already.  However, if SQLite is compiled with the SQLITE_OMIT_AUTOINIT
** compile-time option, then the automatic calls to sqlite3_initialize()
** are omitted and the application must call sqlite3_initialize() directly
** prior to using any other SQLite interface.  For maximum portability,
** it is recommended that applications always invoke sqlite3_initialize()
** directly prior to using any other SQLite interface.  Future releases
** of SQLite may require this.  In other words, the behavior exhibited
** when SQLite is compiled with SQLITE_OMIT_AUTOINIT might become the


** default behavior in some future release of SQLite.
**
** The sqlite3_os_init() routine does operating-system specific
** initialization of the SQLite library.  The sqlite3_os_end()

** routine undoes the effect of sqlite3_os_init().  Typical tasks

** performed by these routines include allocation or deallocation
** of static resources, initialization of global variables,
** setting up a default [sqlite3_vfs] module, or setting up

** a default configuration using [sqlite3_config()].  
**
** The application should never invoke either sqlite3_os_init()
** or sqlite3_os_end() directly.  The application should only invoke
** sqlite3_initialize() and sqlite3_shutdown().  The sqlite3_os_init()
** interface is called automatically by sqlite3_initialize() and 
** sqlite3_os_end() is called by sqlite3_shutdown().  Appropriate
** implementations for sqlite3_os_init() and sqlite3_os_end()
** are built into SQLite when it is compiled for unix, windows, or os/2.
** When built for other platforms (using the SQLITE_OS_OTHER=1 compile-time
** option) the application must supply a suitable implementation for
** sqlite3_os_init() and sqlite3_os_end().  An application-supplied
** implementation of sqlite3_os_init() or sqlite3_os_end()

** must return SQLITE_OK on success and some other [error code] upon
** failure.
*/
int sqlite3_initialize(void);
int sqlite3_shutdown(void);
int sqlite3_os_init(void);
int sqlite3_os_end(void);

/*
** CAPI3REF: Configuring The SQLite Library {F10145}
**
** The sqlite3_config() interface is used to make global configuration
** changes to SQLite in order to tune SQLite to the specific needs of
** the application.  The default configuration is recommended for most
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
** to [database connections] and [prepared statements] so that the
** application is free to use the same [database connection] or the
** same [prepared statement] in different threads at the same time.</dd>
**
** <dt>SQLITE_CONFIG_MALLOC</dt>
** <dd>This option takes four arguments.  The first three
** arguments are pointers to functions that emulate malloc(), free(),
** and realloc(), respectively.  The fourth argument is either a pointer to
** a function that returns the size of a prior allocation, or NULL.  If
** the fourth function is NULL, SQLite will keep track of allocation
** sizes itself.  This option is used to replace the default memory
** allocator with an application-defined memory allocator.</dd>
**
** <dt>SQLITE_CONFIG_MEMSTATS</dt>
** <dd>This option takes single boolean argument which enables or disables
** the collection of memory allocation statistics.  When disabled, the
** following SQLite interfaces become non-operational:
**   <ul>







|
|
<
|







973
974
975
976
977
978
979
980
981

982
983
984
985
986
987
988
989
** to [database connections] and [prepared statements] so that the
** application is free to use the same [database connection] or the
** same [prepared statement] in different threads at the same time.</dd>
**
** <dt>SQLITE_CONFIG_MALLOC</dt>
** <dd>This option takes four arguments.  The first three
** arguments are pointers to functions that emulate malloc(), free(),
** and realloc(), respectively.  The fourth argument must be a pointer to
** a function that returns the size of a prior allocation when handed a pointer

** to the allocation. This option is used to replace the default memory
** allocator with an application-defined memory allocator.</dd>
**
** <dt>SQLITE_CONFIG_MEMSTATS</dt>
** <dd>This option takes single boolean argument which enables or disables
** the collection of memory allocation statistics.  When disabled, the
** following SQLite interfaces become non-operational:
**   <ul>
5619
5620
5621
5622
5623
5624
5625












5626
5627
5628
5629
5630
5631
5632
** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
** implementation is included with the library.  The
** mutex interface routines defined here become external
** references in the SQLite library for which implementations
** must be provided by the application.  This facility allows an
** application that links against SQLite to provide its own mutex
** implementation without having to modify the SQLite core.












**
** {F17011} The sqlite3_mutex_alloc() routine allocates a new
** mutex and returns a pointer to it. {F17012} If it returns NULL
** that means that a mutex could not be allocated. {F17013} SQLite
** will unwind its stack and return an error. {F17014} The argument
** to sqlite3_mutex_alloc() is one of these integer constants:
**







>
>
>
>
>
>
>
>
>
>
>
>







5634
5635
5636
5637
5638
5639
5640
5641
5642
5643
5644
5645
5646
5647
5648
5649
5650
5651
5652
5653
5654
5655
5656
5657
5658
5659
** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
** implementation is included with the library.  The
** mutex interface routines defined here become external
** references in the SQLite library for which implementations
** must be provided by the application.  This facility allows an
** application that links against SQLite to provide its own mutex
** implementation without having to modify the SQLite core.
**
** {F17001} The sqlite3_mutex_init() routine is called once by each
** effective call to [sqlite3_initialize()].  The sqlite3_mutex_init()
** interface initializes the mutex subsystem.  The application should
** never call sqlite3_mutex_init() directly but only indirectly by
** invoking [sqlite3_initialize()].
**
** {F17003} The sqlite3_mutex_end() routine undoes the effect of
** sqlite3_mutex_init().  The sqlite3_mutex_end() interface is called
** by [sqlite3_shutdown()].  The application should never call 
** sqlite3_mutex_end() directly but only indirectly through
** [sqlite3_shutdown()].
**
** {F17011} The sqlite3_mutex_alloc() routine allocates a new
** mutex and returns a pointer to it. {F17012} If it returns NULL
** that means that a mutex could not be allocated. {F17013} SQLite
** will unwind its stack and return an error. {F17014} The argument
** to sqlite3_mutex_alloc() is one of these integer constants:
**
5679
5680
5681
5682
5683
5684
5685
5686
5687
5688
5689
5690
5691
5692
5693
5694
5695
5696
5697
5698
5699
5700

5701
5702
5703
5704
5705

5706
5707
5708
5709
5710
5711
5712
** upon successful entry.  {F17026} Mutexes created using
** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
** {F17027} In such cases the,
** mutex must be exited an equal number of times before another thread
** can enter.  {U17028} If the same thread tries to enter any other
** kind of mutex more than once, the behavior is undefined.
** {F17029} SQLite will never exhibit
** such behavior in its own use of mutexes. {END}
**
** Some systems (ex: windows95) do not the operation implemented by
** sqlite3_mutex_try().  On those systems, sqlite3_mutex_try() will
** always return SQLITE_BUSY.  {F17030} The SQLite core only ever uses
** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
**
** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
** previously entered by the same thread.  {U17032} The behavior
** is undefined if the mutex is not currently entered by the
** calling thread or is not currently allocated.  {F17033} SQLite will
** never do either. {END}
**
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
*/

sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);


/*
** CAPI3REF: Mutex Verifcation Routines {F17080}
**
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
** are intended for use inside assert() statements. {F17081} The SQLite core
** never uses these routines except inside an assert() and applications







|

|


|









>





>







5706
5707
5708
5709
5710
5711
5712
5713
5714
5715
5716
5717
5718
5719
5720
5721
5722
5723
5724
5725
5726
5727
5728
5729
5730
5731
5732
5733
5734
5735
5736
5737
5738
5739
5740
5741
** upon successful entry.  {F17026} Mutexes created using
** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
** {F17027} In such cases the,
** mutex must be exited an equal number of times before another thread
** can enter.  {U17028} If the same thread tries to enter any other
** kind of mutex more than once, the behavior is undefined.
** {F17029} SQLite will never exhibit
** such behavior in its own use of mutexes.
**
** Some systems (ex: windows95) do not support the operation implemented by
** sqlite3_mutex_try().  On those systems, sqlite3_mutex_try() will
** always return SQLITE_BUSY.  {F17030} The SQLite core only ever uses
** sqlite3_mutex_try() as an optimization so this is acceptable behavior.
**
** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
** previously entered by the same thread.  {U17032} The behavior
** is undefined if the mutex is not currently entered by the
** calling thread or is not currently allocated.  {F17033} SQLite will
** never do either. {END}
**
** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
*/
int sqlite3_mutex_init();
sqlite3_mutex *sqlite3_mutex_alloc(int);
void sqlite3_mutex_free(sqlite3_mutex*);
void sqlite3_mutex_enter(sqlite3_mutex*);
int sqlite3_mutex_try(sqlite3_mutex*);
void sqlite3_mutex_leave(sqlite3_mutex*);
int sqlite_mutex_end();

/*
** CAPI3REF: Mutex Verifcation Routines {F17080}
**
** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
** are intended for use inside assert() statements. {F17081} The SQLite core
** never uses these routines except inside an assert() and applications
Changes to src/where.c.
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
** This module contains C code that generates VDBE code used to process
** the WHERE clause of SQL statements.  This module is responsible for
** generating the code that loops through a table looking for applicable
** rows.  Indices are selected and used to speed the search when doing
** so is applicable.  Because this module is responsible for selecting
** indices, you might also think of this module as the "query optimizer".
**
** $Id: where.c,v 1.307 2008/05/30 14:58:37 drh Exp $
*/
#include "sqliteInt.h"

/*
** The number of bits in a Bitmask.  "BMS" means "BitMask Size".
*/
#define BMS  (sizeof(Bitmask)*8)







|







12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
** This module contains C code that generates VDBE code used to process
** the WHERE clause of SQL statements.  This module is responsible for
** generating the code that loops through a table looking for applicable
** rows.  Indices are selected and used to speed the search when doing
** so is applicable.  Because this module is responsible for selecting
** indices, you might also think of this module as the "query optimizer".
**
** $Id: where.c,v 1.308 2008/06/12 00:07:29 drh Exp $
*/
#include "sqliteInt.h"

/*
** The number of bits in a Bitmask.  "BMS" means "BitMask Size".
*/
#define BMS  (sizeof(Bitmask)*8)
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
        bestFlags = flags;
        bestNEq = nEq;
        bestJ = j;
        pLevel->pBestIdx = pIndex;
      }
      if( doNotReorder ) break;
    }
    WHERETRACE(("*** Optimizer choose table %d for loop %d\n", bestJ,
           pLevel-pWInfo->a));
    if( (bestFlags & WHERE_ORDERBY)!=0 ){
      *ppOrderBy = 0;
    }
    andFlags &= bestFlags;
    pLevel->flags = bestFlags;
    pLevel->pIdx = pBest;







|







2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
        bestFlags = flags;
        bestNEq = nEq;
        bestJ = j;
        pLevel->pBestIdx = pIndex;
      }
      if( doNotReorder ) break;
    }
    WHERETRACE(("*** Optimizer selects table %d for loop %d\n", bestJ,
           pLevel-pWInfo->a));
    if( (bestFlags & WHERE_ORDERBY)!=0 ){
      *ppOrderBy = 0;
    }
    andFlags &= bestFlags;
    pLevel->flags = bestFlags;
    pLevel->pIdx = pBest;