From d2d4a6b00dea9fa9cb36478377b886bc729e591e Mon Sep 17 00:00:00 2001 From: drh Date: Tue, 10 Jan 2006 15:18:27 +0000 Subject: [PATCH] Updates to the C-API documentation. Change the parameter type of sqlite3_soft_heap_limit to integer. (CVS 2903) FossilOrigin-Name: bdd35e9fbb651fe7a1ed5042923c9529c3c5ab7c --- manifest | 18 ++--- manifest.uuid | 2 +- src/sqlite.h.in | 4 +- src/sqliteInt.h | 17 ++-- src/util.c | 6 +- www/capi3ref.tcl | 197 ++++++++++++++++++++++++++++++++++++++++++----- 6 files changed, 203 insertions(+), 41 deletions(-) diff --git a/manifest b/manifest index a1b404d92c..681fed375a 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Move\sthe\simplementation\sof\ssqlite3_enable_shared_cache\sfrom\sbtree.c\sto\smain.c.\s(CVS\s2902) -D 2006-01-10T13:58:48 +C Updates\sto\sthe\sC-API\sdocumentation.\s\sChange\sthe\sparameter\stype\sof\nsqlite3_soft_heap_limit\sto\sinteger.\s(CVS\s2903) +D 2006-01-10T15:18:28 F Makefile.in ab3ffd8d469cef4477257169b82810030a6bb967 F Makefile.linux-gcc aee18d8a05546dcf1888bd4547e442008a49a092 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028 @@ -69,8 +69,8 @@ F src/random.c d40f8d356cecbd351ccfab6eaedd7ec1b54f5261 F src/select.c acfeda959fe07eac04950d945ac7ec0518ef4b7d F src/server.c 42a2bd02eec5018098a96e08f7a923f4965a2b1d F src/shell.c 66b073375efbdee19045e7e0cd38b85f9aff71da -F src/sqlite.h.in 537bac9e9ef703695268aaad5c56b6bf64f815be -F src/sqliteInt.h 01703e82a73f0e4558f8862c35a4b287f587573c +F src/sqlite.h.in 821b93f918d126c54d9a91fc928434945655edc3 +F src/sqliteInt.h f3fe5c8b7d3a7491d6f47f0605b7ed70f146c59f F src/table.c 486dcfce532685b53b5a2b5da8bba0ded6fb2316 F src/tclsqlite.c d650bea0248fc0a310ddc2cb94273a3a5021fddf F src/test1.c 5f634ce9aa452dbcc362993c9612047df800216c @@ -85,7 +85,7 @@ F src/tokenize.c 196486012c871cdcad6cc84a820cc988603f1b9d F src/trigger.c 883b5f3b97137fbe417e3337c3fa20ac8e9c1ae5 F src/update.c e09da54cb8e042f89f4177f4ef879b594d8ab946 F src/utf.c b7bffac4260177ae7f83c01d025fe0f5ed70ce71 -F src/util.c 264083f0de25b92c362e88a23402cc76e93613ba +F src/util.c 5d5792d4a4dda20d70fdfb973ed8a5ed71fea98c F src/vacuum.c f5a068096b22fad438bf1f1cf69ccb7f9e8cc7fb F src/vdbe.c 490b9b48a8f616b9a15b0151b86212b0fab311b2 F src/vdbe.h 8729a4ee16ff9aeab2af9667df3cf300ff978e13 @@ -297,7 +297,7 @@ F www/audit.tcl 90e09d580f79c7efec0c7d6f447b7ec5c2dce5c0 F www/autoinc.tcl b357f5ba954b046ee35392ce0f884a2fcfcdea06 F www/c_interface.tcl b51b08591554c16a0c3ef718364a508ac25abc7e F www/capi3.tcl 7a7cc225fe02eb7ab861a6019b08baa0014409e1 -F www/capi3ref.tcl c4bf23a0110ad0ffdf4fe6b74d464965116dcea4 +F www/capi3ref.tcl 5d67be5af0c6edc888dec19f99839e332e4bb470 F www/changes.tcl 567069a3dc7d066f3687fe3697be62e6dd19e671 F www/common.tcl 14d121c28532ad20c3e349caa4db708b0b822083 F www/compile.tcl 276546d7eb445add5a867193bbd80f6919a6b084 @@ -340,7 +340,7 @@ F www/tclsqlite.tcl bb0d1357328a42b1993d78573e587c6dcbc964b9 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0 F www/version3.tcl a99cf5f6d8bd4d5537584a2b342f0fb9fa601d8b F www/whentouse.tcl 97e2b5cd296f7d8057e11f44427dea8a4c2db513 -P 9c18a1ce1e7ff6a02eb0f9ce344cab9660819740 -R d6f71e8344cce361f5d74f812339b551 +P 4f2ec95283f1ae0a28b2f9ce0afc5a7203de87fb +R 6f27b31eddededb37a4ce53e31f18e64 U drh -Z a1174a32567e13b6cc8e755afde6cc38 +Z abf90018e50b865b136d9f985b2b2657 diff --git a/manifest.uuid b/manifest.uuid index 64c55b7e58..367af7c8c5 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -4f2ec95283f1ae0a28b2f9ce0afc5a7203de87fb \ No newline at end of file +bdd35e9fbb651fe7a1ed5042923c9529c3c5ab7c \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 5395ef7199..c43b7cd0de 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -12,7 +12,7 @@ ** This header file defines the interface that the SQLite library ** presents to client programs. ** -** @(#) $Id: sqlite.h.in,v 1.153 2006/01/09 09:59:49 danielk1977 Exp $ +** @(#) $Id: sqlite.h.in,v 1.154 2006/01/10 15:18:28 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ @@ -1361,7 +1361,7 @@ int sqlite3_release_memory(int); ** SQLITE_OMIT_MEMORY_MANAGEMENT option set. It is a no-op unless ** memory-management has been enabled. */ -void sqlite3_soft_heap_limit(sqlite_int64); +void sqlite3_soft_heap_limit(int); /* ** Undo the hack that converts floating point types to integer for diff --git a/src/sqliteInt.h b/src/sqliteInt.h index b9e2ac8540..f3a9227f7d 100644 --- a/src/sqliteInt.h +++ b/src/sqliteInt.h @@ -11,7 +11,7 @@ ************************************************************************* ** Internal interface definitions for SQLite. ** -** @(#) $Id: sqliteInt.h,v 1.458 2006/01/10 12:31:40 danielk1977 Exp $ +** @(#) $Id: sqliteInt.h,v 1.459 2006/01/10 15:18:28 drh Exp $ */ #ifndef _SQLITEINT_H_ #define _SQLITEINT_H_ @@ -294,8 +294,8 @@ struct ThreadData { #ifndef SQLITE_OMIT_MEMORY_MANAGEMENT u8 useMemoryManagement; /* True if memory-management is enabled */ - i64 nSoftHeapLimit; /* Suggested max mem allocation. No limit if <0 */ - i64 nAlloc; /* Number of bytes currently allocated */ + int nSoftHeapLimit; /* Suggested max mem allocation. No limit if <0 */ + int nAlloc; /* Number of bytes currently allocated */ Pager *pPager; /* Linked list of all pagers in this thread */ #endif @@ -305,7 +305,7 @@ struct ThreadData { #endif #ifdef SQLITE_MEMDEBUG - i64 nMaxAlloc; /* High water mark of ThreadData.nAlloc */ + int nMaxAlloc; /* High water mark of ThreadData.nAlloc */ int mallocAllowed; /* assert() in sqlite3Malloc() if not set */ int isFail; /* True if all malloc() calls should fail */ const char *zFile; /* Filename to associate debugging info with */ @@ -674,8 +674,6 @@ struct CollSeq { ** is generated for each row of the table. Table.hasPrimKey is true if ** the table has any PRIMARY KEY, INTEGER or otherwise. ** -** TODO: This comment is out of date. Table.iDb no longer exists. -** ** Table.tnum is the page number for the root BTree page of the table in the ** database file. If Table.iDb is the index of the database table backend ** in sqlite.aDb[]. 0 is for the main database and 1 is for the file that @@ -696,6 +694,7 @@ struct Table { int tnum; /* Root BTree node for this table (see note above) */ Select *pSelect; /* NULL for tables. Points to definition if a view. */ u8 readOnly; /* True if this table should not be written by the user */ +// u8 iDb; /* Index into sqlite.aDb[] of the backend for this table */ u8 isTransient; /* True if automatically deleted when VDBE finishes */ u8 hasPrimKey; /* True if there exists a primary key */ u8 keyConf; /* What to do in case of uniqueness conflict on iPKey */ @@ -807,7 +806,7 @@ struct KeyInfo { u8 enc; /* Text encoding - one of the TEXT_Utf* values */ u8 incrKey; /* Increase 2nd key by epsilon before comparison */ int nField; /* Number of entries in aColl[] */ - u8 *aSortOrder; /* If defined and aSortOrder[i] is true, sort DESC */ + u8 *aSortOrder; /* If defined an aSortOrder[i] is true, sort DESC */ CollSeq *aColl[1]; /* Collating sequence for each term of the key */ }; @@ -846,9 +845,10 @@ struct Index { int tnum; /* Page containing root of this index in database file */ u8 onError; /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */ u8 autoIndex; /* True if is automatically created (ex: by UNIQUE) */ + // u8 iDb; /* Index in sqlite.aDb[] of where this index is stored */ char *zColAff; /* String defining the affinity of each column */ Index *pNext; /* The next index associated with the same table */ - Schema *pSchema; /* Schema containing this index */ + Schema *pSchema; KeyInfo keyInfo; /* Info on how to order keys. MUST BE LAST */ }; @@ -958,6 +958,7 @@ struct AggInfo { struct Expr { u8 op; /* Operation performed by this node */ char affinity; /* The affinity of the column or 0 if not a column */ +//u8 iDb; /* Database referenced by this expression */ u8 flags; /* Various flags. See below */ CollSeq *pColl; /* The collation type of the column or 0 */ Expr *pLeft, *pRight; /* Left and right subnodes */ diff --git a/src/util.c b/src/util.c index 3cfc37276a..1a8287b072 100644 --- a/src/util.c +++ b/src/util.c @@ -14,7 +14,7 @@ ** This file contains functions for allocating memory, comparing ** strings, and stuff like that. ** -** $Id: util.c,v 1.165 2006/01/10 07:14:24 danielk1977 Exp $ +** $Id: util.c,v 1.166 2006/01/10 15:18:28 drh Exp $ */ #include "sqliteInt.h" #include "os.h" @@ -71,7 +71,7 @@ ** Set the soft heap-size limit for the current thread. Passing a negative ** value indicates no limit. */ -void sqlite3_soft_heap_limit(sqlite_int64 n){ +void sqlite3_soft_heap_limit(int n){ sqlite3ThreadData()->nSoftHeapLimit = n; } @@ -524,7 +524,7 @@ static void OSMALLOC_FAILED(){ #ifndef SQLITE_OMIT_MEMORY_MANAGEMENT static void handleSoftLimit(int n){ ThreadData *pTsd = sqlite3ThreadData(); - pTsd->nAlloc += (i64)n; + pTsd->nAlloc += n; if( n>0 && pTsd->nSoftHeapLimit>0 ){ while( pTsd->nAlloc>pTsd->nSoftHeapLimit && sqlite3_release_memory(n) ); } diff --git a/www/capi3ref.tcl b/www/capi3ref.tcl index c14582dd2f..61567c9caf 100644 --- a/www/capi3ref.tcl +++ b/www/capi3ref.tcl @@ -1,4 +1,4 @@ -set rcsid {$Id: capi3ref.tcl,v 1.25 2005/12/02 01:57:43 drh Exp $} +set rcsid {$Id: capi3ref.tcl,v 1.26 2006/01/10 15:18:28 drh Exp $} source common.tcl header {C/C++ Interface For SQLite Version 3} puts { @@ -1144,23 +1144,10 @@ api {} { api {} { int sqlite3_global_recover(); } { - This function is called to recover from a malloc() failure that occured - within the SQLite library. Normally, after a single malloc() fails the - library refuses to function (all major calls return SQLITE_NOMEM). - This function restores the library state so that it can be used again. - - All existing statements (sqlite3_stmt pointers) must be finalized or - reset before this call is made. Otherwise, SQLITE_BUSY is returned. - If any in-memory databases are in use, either as a main or TEMP - database, SQLITE_ERROR is returned. In either of these cases, the - library is not reset and remains unusable. - - This function is *not* threadsafe. Calling this from within a threaded - application when threads other than the caller have used SQLite is - dangerous and will almost certainly result in malfunctions. - - This functionality can be omitted from a build by defining the - SQLITE_OMIT_GLOBALRECOVER at compile time. + This function is used to be involved in recovering from out-of-memory + errors. But as of SQLite version 3.3.0, out-of-memory recovery is + automatic and this routine now does nothing. THe interface is retained + to avoid link errors with legacy code. } api {} { @@ -1187,6 +1174,180 @@ api {} { the statement in the first place. } +api {} { + void *sqlite3_update_hook( + sqlite3*, + void(*)(void *,int ,char const *,char const *,sqlite_int64), + void* + ); +} { + Register a callback function with the database connection identified by the + first argument to be invoked whenever a row is updated, inserted or deleted. + Any callback set by a previous call to this function for the same + database connection is overridden. + + The second argument is a pointer to the function to invoke when a + row is updated, inserted or deleted. The first argument to the callback is + a copy of the third argument to sqlite3_update_hook. The second callback + argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending + on the operation that caused the callback to be invoked. The third and + fourth arguments to the callback contain pointers to the database and + table name containing the affected row. The final callback parameter is + the rowid of the row. In the case of an update, this is the rowid after + the update takes place. + + The update hook is not invoked when internal system tables are + modified (i.e. sqlite_master and sqlite_sequence). + + If another function was previously registered, its pArg value is returned. + Otherwise NULL is returned. + + See also: sqlite3_commit_hook(), sqlite3_rollback_hook() +} + +api {} { + void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*); +} { + Register a callback to be invoked whenever a transaction is rolled + back. + + The new callback function overrides any existing rollback-hook + callback. If there was an existing callback, then it's pArg value + (the third argument to sqlite3_rollback_hook() when it was registered) + is returned. Otherwise, NULL is returned. + + For the purposes of this API, a transaction is said to have been + rolled back if an explicit "ROLLBACK" statement is executed, or + an error or constraint causes an implicit rollback to occur. The + callback is not invoked if a transaction is automatically rolled + back because the database connection is closed. +} + +api {} { + int sqlite3_enable_shared_cache(int); +} { + This routine enables or disables the sharing of the database cache + and schema data structures between connections to the same database. + Sharing is enabled if the argument is true and disabled if the argument + is false. + + Cache sharing is enabled and disabled on a thread-by-thread basis. + Each call to this routine enables or disables cache sharing only for + connections created in the same thread in which this routine is called. + There is no mechanism for sharing cache between database connections + running in different threads. + + This routine must not be called when any database connections + are active in the current thread. Enabling or disabling shared + cache while there are active database connections will result + in memory corruption. + + For any given database connection, SQLite requires that the + following routines always be called from the same thread: + sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(), + sqlite3_finalize(), and sqlite3_close(). On some operating systems + (ex: windows and linux 2.6) you can get away with calling these routines + from different threads as long as their executions never overlap in time + and the shared cache is disabled. + But when the shared cache is enabled, some information about the + database connection is stored in thread-specific storage so that it + will be available for sharing with other connections. Consequently, + the previously enumerated routines must always be called from the + same thread when shared cache is enabled, regardless of what operating + system is used. + + This routine returns SQLITE_OK if shared cache was + enabled or disabled successfully. An error code is returned + otherwise. + + Shared cache is disabled by default for backward compatibility. +} + +api {} { + int sqlite3_enable_memory_management(int); +} { + This routine enables or disables heap memory management for the + thread in which it is called. Memory management is enabled if + the argument is true and disabled if the argument is false. + + This routine must not be called when any database connections + are active in the current thread. Enabling or disabling memory + management while there are active database connections will result + in memory corruption. + + When memory management is enabled, SQLite tries to automatically + recover from out-of-memory errors by freeing unused cache memory + and retrying the allocation. + This allows operations to continue when available memory is limit + though with some loss of performance due to the reduction in cache + size. + + The sqlite3_soft_heap_limit() API can be used to restrict SQLite's + heap memory usage to a preset amount so that the reclamation of + cache begins to occur before memory is exhausted. + + Memory management is enabled and disabled on a thread-by-thread basis. + Each call to this routine enables or disabled memory management only for + database connections created and used in the same thread in which this + routine is called. + + For any given database connection, SQLite requires that the + following routines always be called from the same thread: + sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(), + sqlite3_finalize(), and sqlite3_close(). On some operating systems + (ex: windows and linux 2.6) you can get away with calling these routines + from different threads as long as their executions never overlap in time + and memory management is disabled. + But when the memory management is enabled, some information about the + database connections is stored in thread-specific storage so that it + will be available to remediate memory shortages. Consequently, + the previously enumerated routines must always be called from the + same thread when memory management is enabled, regardless of what + operating system is used. + + This routine returns SQLITE_OK if the memory management module was + enabled or disabled successfully. An error code is returned + otherwise. + + Memory management is disabled by default for backwards compatibility + and because it is normally only useful for embedded devices. The + code that implements the memory management feature can be omitted by + recompiling SQLite with the SQLITE_OMIT_MEMORY_MANAGEMENT macro defined. +} + +api {} { + int sqlite3_release_memory(int N); +} { + This routine attempts to free at least N bytes of memory from the caches + of database connecions that were created in the same thread from which this + routine is called. The value returned is the number of bytes actually + freed. + + If memory management has not been enabled by calling + sqlite3_enable_memory_management() then this routine is a no-op + and always returns 0. +} + +api {} { + void sqlite3_soft_heap_limit(int N); +} { + This routine sets the soft heap limit for the current thread to N. + If memory management is enabled on the thread by the + sqlite3_enable_memory_management() function and the total heap usage + by SQLite in that thread exceeds N, then sqlite3_release_memory() is + called to try to reduce the memory usage below the soft limit. + + A negative value for N means that there is no soft heap limit and + sqlite3_release_memory() will only be called when memory is exhaused. + The default value for the soft heap limit is negative. + + SQLite makes a best effort to honor the soft heap limit. But if it + is unable to reduce memory usage below the soft limit, execution will + continue without error or notification. This is way the limit is + called a "soft" limit. It is advisory only. + + If memory management is not enabled, the soft heap limit is ignored. +} set n 0 set i 0 -- 2.47.2