From: drh Date: Mon, 9 Jun 2008 21:57:22 +0000 (+0000) Subject: Initial attempt at defining the sqlite3_initialize() and sqlite3_shutdown() X-Git-Tag: version-3.6.10~979 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=673299b7729d25e64991955b2c02bc595e8d5d74;p=thirdparty%2Fsqlite.git Initial attempt at defining the sqlite3_initialize() and sqlite3_shutdown() interfaces. (CVS 5198) FossilOrigin-Name: 220bfd1f5cef0dfa8b800faa814ad4dc1456ced4 --- diff --git a/manifest b/manifest index 29c2b988b9..15ecbdc8ae 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Moved\sdeclaration\sof\sint\snPage;\sto\stop\sof\sblock\sto\ssilence\spicky\scompilers\s(MSVC).\s(CVS\s5197) -D 2008-06-09T19:27:12 +C Initial\sattempt\sat\sdefining\sthe\ssqlite3_initialize()\sand\ssqlite3_shutdown()\ninterfaces.\s(CVS\s5198) +D 2008-06-09T21:57:23 F Makefile.arm-wince-mingw32ce-gcc ac5f7b2cef0cd850d6f755ba6ee4ab961b1fadf7 F Makefile.in ce92ea8dc7adfb743757794f51c10d1b0d9c55e4 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -128,7 +128,7 @@ F src/mutex_os2.c 2911ea96955ab6cba734cc4ad903fe76f834b39e F src/mutex_unix.c 466d20378a0645fea64c3f2e2669c33b7802df56 F src/mutex_w32.c 133698096a2c4e81cd11ea6f4de7891c66f7b9f7 F src/os.c 284abcb97ffdaf5f0b08fa4c5fe1fe93dd86b416 -F src/os.h 333a53ddaf25697577a58165e1216c6cb3ccf056 +F src/os.h c9a7f94e80193fd4cf27f5c5698eb56753f1b05a F src/os_common.h 24525d8b7bce66c374dfc1810a6c9043f3359b60 F src/os_os2.c 1578149e21c4eac42c7f230a6f40500846f8e781 F src/os_unix.c 47936aee8265e482faa626141d97d896aa981ef4 @@ -142,7 +142,7 @@ F src/printf.c f2d4f6c5b0ec24b643e85fe60258adad8b1f6acc F src/random.c 2b2db2de4ab491f5a14d3480466f8f4b5a5db74a F src/select.c 669687459e7d0193c89de06c5dbed55b4a41191c F src/shell.c a12ea645271b7876c8f080146f48e20b00d367ec -F src/sqlite.h.in 48d90217674a919cc96cdeb6c26fe674eddfa23a +F src/sqlite.h.in 5956da2f10f6bf7bb008b3932da7921a1b08893f F src/sqlite3ext.h faacd0e6a81aabee0861c6d7883c9172e74ef5b3 F src/sqliteInt.h 1593404d8aee13687ca7b5d552cb153de7441bef F src/sqliteLimit.h f435e728c6b620ef7312814d660a81f9356eb5c8 @@ -592,7 +592,7 @@ F tool/speedtest16.c c8a9c793df96db7e4933f0852abb7a03d48f2e81 F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 1dbced29de5f59ba2ebf877edcadf171540374d1 F tool/speedtest8inst1.c c65494ca99d1e09c246dfe37a7ca7a354af9990f -P c1d877feb530b5cdaad55da3dbbb7c2596a10c49 -R 81c98d48a45b9042d962ee079ffcf761 -U shane -Z 5e9347ffb7b52be63ae88c924696d76b +P 120bffff747592f1ab6ed02713a712cc74c12528 +R 8d8e29a55f02f2444346b9de32d470a6 +U drh +Z 41d7f329a14fa126f2a7b2f5f5beb340 diff --git a/manifest.uuid b/manifest.uuid index b56f9f1256..83d3b20c6a 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -120bffff747592f1ab6ed02713a712cc74c12528 \ No newline at end of file +220bfd1f5cef0dfa8b800faa814ad4dc1456ced4 \ No newline at end of file diff --git a/src/os.h b/src/os.h index c0f0e4ddf6..d0af1f469d 100644 --- a/src/os.h +++ b/src/os.h @@ -17,7 +17,7 @@ ** This header file is #include-ed by sqliteInt.h and thus ends up ** being included by every source file. ** -** $Id: os.h,v 1.102 2008/06/05 11:39:11 danielk1977 Exp $ +** $Id: os.h,v 1.103 2008/06/09 21:57:23 drh Exp $ */ #ifndef _SQLITE_OS_H_ #define _SQLITE_OS_H_ @@ -253,7 +253,6 @@ int sqlite3OsDeviceCharacteristics(sqlite3_file *id); int sqlite3OsOpen(sqlite3_vfs *, const char *, sqlite3_file*, int, int *); int sqlite3OsDelete(sqlite3_vfs *, const char *, int); int sqlite3OsAccess(sqlite3_vfs *, const char *, int, int *pResOut); -int sqlite3OsGetTempname(sqlite3_vfs *, int, char *); int sqlite3OsFullPathname(sqlite3_vfs *, const char *, int, char *); #ifndef SQLITE_OMIT_LOAD_EXTENSION void *sqlite3OsDlOpen(sqlite3_vfs *, const char *); diff --git a/src/sqlite.h.in b/src/sqlite.h.in index fda0fe4701..0bfbc8ddd2 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -30,7 +30,7 @@ ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** -** @(#) $Id: sqlite.h.in,v 1.322 2008/06/06 15:49:30 danielk1977 Exp $ +** @(#) $Id: sqlite.h.in,v 1.323 2008/06/09 21:57:23 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -153,6 +153,7 @@ int sqlite3_libversion_number(void); */ int sqlite3_threadsafe(void); + /* ** CAPI3REF: Database Connection Handle {F12000} ** KEYWORDS: {database connection} {database connections} @@ -841,6 +842,209 @@ struct sqlite3_vfs { #define SQLITE_ACCESS_READWRITE 1 #define SQLITE_ACCESS_READ 2 +/* +** CAPI3REF: SQLite Configuration Definition {F10180} +** +** A pointer to an instance of the sqlite3_configuration structure +** may be optionally passed into the [sqlite3_initialize()] interface +** in order to set up a custom configuration for the SQLite library. +** +** The xMemInit() routine is called with pMemClientData as an argument +** at [sqlite3_initialize()]. xMemShutdown is called at +** [sqlite3_shutdown()]. +** +** If the xMemSize pointer may be omitted, +** but if it is, then the following SQLite interfaces will not work +** correctly: +** +** +** +** If xMemSize is defined, then SQLite will hold the +** [SQLITE_MUTEX_STATIC_MEM] mutex will accessing any of xMemAlloc, +** xMemRealloc, or xMemFree. If xMemSize is NULL then the +** [SQLITE_MUTEX_STATIC_MEM] mutex is never used. +** +** The xPageAlloc and xPageFree functions are alternative memory +** allocators for page cache pages. If undefined +** then xMemAlloc and xMemFree will be used. +** +** The xTempAlloc and xTempFree functions are alternative memory +** allocators for short-lived temporary space. +** If undefined then xMemAlloc and xMemFree above will be used. +** +** None of the mutex subsystem fields are ever accessed +** if SQLite is compiled with -DSQLITE_THREADSAFE=0. +** +** The xMutexInit routine is called by each effective [sqlite3_initialize()] +** and xMutexShutdown is called by each valid [sqlite3_shutdown()]. +** +** If bSerializeConnection is true then SQLite will use one or more +** [SQLITE_MUTEX_RECURSIVE] mutexes to serialize access to +** [database connection] and [prepared statement] objects. If +** bSerializeConnection is false, then it is the application's +** responsibiility to serialize access to these objects. +** +** The xMutexTry interface is an optimization that does not +** come up often and can be omitted. If omitted, xMutexEnter +** will be used in its place. +** +** The xMutexHeld and xMutexNotHeld interfaces are used for testing +** purposes only. It is ok for these functions to report false +** positives. These functions are only used within the argument of +** assert() statements. +*/ +typedef struct sqlite3_configuration sqlite3_configuration; +struct sqlite3_configuration { + /* Memory allocation subsystem interface */ + void *pMemClientData; /* Argument to xMemInit and xMemShutdown */ + int (*xMemInit)(void*); /* May be NULL */ + int (*xMemShutdown)(void*); /* May be NULL */ + void *(*xMemAlloc)(int); + void *(*xMemRealloc)(void*, int); + void (*xMemFree)(void*); + int (*xMemSize)(void*); /* May be NULL */ + /* Alternative memory allocators for page cache and transient storage */ + void *(*xPageAlloc)(int iSize); /* May be NULL */ + void (*xPageFree)(void*, int iSize); /* May be NULL */ + void *(*xTempAlloc)(int iSize); /* May be NULL */ + void (*xTempFree)(void*); /* May be NULL */ + /* Parameters optionally used by some alternative memory allocators. */ + sqlite3_int64 nMemHeap; /* Total memory available for allocating */ + void *pMemHeap; /* Pointer to memory space to be allocated */ + int mnMemAlloc; /* Minimum allocation size */ + int mxMemAlloc; /* Maximum allocation size */ + int nTemp; /* Maximum temp space available */ + int mxTemp; /* Maximum temp space allocation size */ + /* Mutex methods */ + void *pMutexClientData; /* Arg to xMutexInit and xMutexShutdown */ + int (*xMutexInit)(void*); /* May be NULL */ + int (*xMutexShutdown)(void*); /* May be NULL */ + int bSerializeConnection; + sqlite3_mutex *(*xMutexAlloc)(int mutexType); + void (*xMutexFree)(sqlite3_mutex*); + void (*xMutexEnter)(sqlite3_mutex*); + int (*xMutexTry)(sqlite3_mutex*); /* May be NULL */ + void (*xMutexLeave)(sqlite3_mutex*); + int (*xMutexHeld)(sqlite3_mutex*); /* May be NULL */ + int (*xMutexNotHeld)(sqlite3_mutex*); /* May be NULL */ +}; + +/* +** CAPI3REF: Initialize The SQLite Library {F10140} +** +** The sqlite3_initialize() interface is used to initialize the +** SQLite library. The sqlite3_initialize() routine is only effective +** the first time it is called within a process, or the first time it +** is called after a call to sqlite3_shutdown(). Other SQLite APIs +** might invoke sqlite3_initialize() internally, so in order for +** an application to be sure that its call to sqlite3_initialize() +** is first, it should invoke sqlite3_initialize() prior to invoking any +** other SQLite interface (with the possible exception of +** sqlite3_default_configuration() as described below.) +** +** If the parameter to sqlite3_initialize() is NULL then a default +** configuration is used. A copy of the default configuration can +** be obtained using the sqlite3_default_configuration() interface. +** An application that only wants to make slight adjustments to the +** configuration can invoke sqlite3_default_configuration() to populate +** an initially empty [sqlite3_configuration] structure, make whatever +** changes to that structure are desired, then invoke sqlite3_initialize() +** to register the new configuration. +** +** The sqlite3_default_configuration() interface does not invoke +** sqlite3_initialize() so an application can call +** sqlite3_default_configuration() before sqlite3_initialize() and still +** be assured that its call to sqlite3_initialize() is the first. +** The configuration returned by sqlite3_default_configuration() is +** a compiled-in default. Changing the configuration using a call +** to sqlite3_initialize() does not change the value returned by +** sqlite3_default_configuration(). The sqlite3_default_configuration() +** interface is threadsafe. +** +** The second parameter to both sqlite3_initialize() and +** sqlite3_default_configuration() should always be the +** SQLITE_VERSION_NUMBER constant. The content of the +** [sqlite3_configuration] structure may change in future versions of +** SQLite and so the sqlite3_initialize() and +** sqlite3_default_configuration()) functions need to know the +** version of the header file that defined the [sqlite3_configuration] +** structure in order to use the structure correctly. +** +** The sqlite3_default_configuration() interface returns SQLITE_OK on +** success. If the iVersion parameter is such that SQLite is unable +** to fill in the [sqlite3_configuration] structure, then the interface +** will return SQLITE_ERROR. +** +** The application must insure that the initial call to sqlite3_initialize() +** is serialized. This means that multi-threaded applications should invoke +** sqlite3_initialize() in the main thread prior to starting any other +** threads that might use SQLite. In the general case, SQLite depends on +** the application to serialize access to sqlite3_initialize() because SQLite +** cannot create a mutex to do the serialization itself until after +** sqlite3_initialize() has run. In the current unix and win32 +** implementations, SQLite is able to serialize access to sqlite3_initialize() +** on its own, but this is not true for all embedded platforms and might +** not be true for unix and win32 in future releases. +** +** SQLite makes a copy of the content of the [sqlite3_configuration] structure +** that is passed into sqlite3_initialize(). Hence the application is free +** to deallocate or modify the [sqlite3_configuration] structure after +** sqlite3_initialize() returns. +** +** Once sqlite3_initialize() has been successfully invoked once, all +** subsequent calls to sqlite3_initialize() are ignored until +** sqlite3_shutdown() is run. After sqlite3_shutdown() has been invoked, +** the next call to sqlite3_initialize() is effective for a single call +** but after that sqlite3_initialize() again becomes a no-up. In other words, +** a call to sqlite3_initialize() is only effective if it is the first +** invocation for the process or if it is invoked immediately after a +** call to sqlite3_shutdown(). +** +** The sqlite3_initialize() routine returns SQLITE_OK on success. +** If sqlite3_initialize() returns any value other than SQLITE_OK then +** the SQLite library is not safe to use. +** +** The sqlite3_shutdown() interface clears a prior initialization and +** enables SQLite to be reinitialized. The application must insure that +** the sqlite3_shutdown() interface is only called when there are no +** outstanding memory allocations or mutexes, no open database connections, +** and no other SQLite interfaces are being called in different threads. +** If sqlite3_shutdown() is called while there are still outstanding +** memory allocations or mutexes, or open database connections, or while +** another thread is making a call to any SQLite interface, then the +** result is undefined and could be segmentation fault or other +** fatal application error. +** +** As currently implemented, sqlite3_shutdown() always returns SQLITE_OK, +** however this might change in a future release of SQLite. +** +** The sqlite3_on_shutdown() interface registers a callback to be invoked +** the next time sqlite3_shutdown() is called. Each callback is invoked +** only once at the next sqlite3_shutdown() call. Callbacks must be +** reregistered in order to be run on subsequent sqlite3_shutdown() calls. +** Each call to sqlite3_on_shutdown() allocates a little bit of memory +** used to hold the callback function pointer and the corresponding +** application data pointer. The memory is freed after the callback is +** invoked. The callbacks registered by sqlite3_on_callback() are invoked +** in the order in which they were registered. If the same callback is +** registered multiple times, it is invoked multiple times. All callbacks +** are invoked prior to the xMemShutdown() and xMutexShutdown() methods +** of the sqlite3_configuration structure. +** +** The sqlite3_on_shutdown() interface returns SQLITE_OK on success, or +** SQLITE_NOMEM if it is unable to allocate memory to hold the pointer +** to the callback function and corresponding application data pointer. +*/ +int sqlite3_initialize(const sqlite3_configuration*, int iVersion); +int sqlite3_default_configuration(sqlite3_configuration*, int iVersion); +int sqlite3_on_shutdown(void (*)(void*), void*); +int sqlite3_shutdown(void); + + /* ** CAPI3REF: Enable Or Disable Extended Result Codes {F12200} **