/ Check-in [bdd35e9f]
Login

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

Overview
Comment:Updates to the C-API documentation. Change the parameter type of sqlite3_soft_heap_limit to integer. (CVS 2903)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: bdd35e9fbb651fe7a1ed5042923c9529c3c5ab7c
User & Date: drh 2006-01-10 15:18:28
Context
2006-01-10
17:58
Store collation sequence names instead of pointers in sharable schema data structures. (CVS 2904) check-in: 0f0213be user: danielk1977 tags: trunk
15:18
Updates to the C-API documentation. Change the parameter type of sqlite3_soft_heap_limit to integer. (CVS 2903) check-in: bdd35e9f user: drh tags: trunk
13:58
Move the implementation of sqlite3_enable_shared_cache from btree.c to main.c. (CVS 2902) check-in: 4f2ec952 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

     8      8   **    May you find forgiveness for yourself and forgive others.
     9      9   **    May you share freely, never taking more than you give.
    10     10   **
    11     11   *************************************************************************
    12     12   ** This header file defines the interface that the SQLite library
    13     13   ** presents to client programs.
    14     14   **
    15         -** @(#) $Id: sqlite.h.in,v 1.153 2006/01/09 09:59:49 danielk1977 Exp $
           15  +** @(#) $Id: sqlite.h.in,v 1.154 2006/01/10 15:18:28 drh Exp $
    16     16   */
    17     17   #ifndef _SQLITE3_H_
    18     18   #define _SQLITE3_H_
    19     19   #include <stdarg.h>     /* Needed for the definition of va_list */
    20     20   
    21     21   /*
    22     22   ** Make sure we can call this stuff from C++.
................................................................................
  1357   1357   ** sufficient memory to prevent the limit from being exceeded, the memory is
  1358   1358   ** allocated anyway and the current operation proceeds.
  1359   1359   **
  1360   1360   ** This function is only available if the library was compiled without the 
  1361   1361   ** SQLITE_OMIT_MEMORY_MANAGEMENT option set. It is a no-op unless 
  1362   1362   ** memory-management has been enabled.
  1363   1363   */
  1364         -void sqlite3_soft_heap_limit(sqlite_int64);
         1364  +void sqlite3_soft_heap_limit(int);
  1365   1365   
  1366   1366   /*
  1367   1367   ** Undo the hack that converts floating point types to integer for
  1368   1368   ** builds on processors without floating point support.
  1369   1369   */
  1370   1370   #ifdef SQLITE_OMIT_FLOATING_POINT
  1371   1371   # undef double
  1372   1372   #endif
  1373   1373   
  1374   1374   #ifdef __cplusplus
  1375   1375   }  /* End of the 'extern "C"' block */
  1376   1376   #endif
  1377   1377   #endif

Changes to src/sqliteInt.h.

     7      7   **    May you do good and not evil.
     8      8   **    May you find forgiveness for yourself and forgive others.
     9      9   **    May you share freely, never taking more than you give.
    10     10   **
    11     11   *************************************************************************
    12     12   ** Internal interface definitions for SQLite.
    13     13   **
    14         -** @(#) $Id: sqliteInt.h,v 1.458 2006/01/10 12:31:40 danielk1977 Exp $
           14  +** @(#) $Id: sqliteInt.h,v 1.459 2006/01/10 15:18:28 drh Exp $
    15     15   */
    16     16   #ifndef _SQLITEINT_H_
    17     17   #define _SQLITEINT_H_
    18     18   
    19     19   /*
    20     20   ** Extra interface definitions for those who need them
    21     21   */
................................................................................
   290    290   */
   291    291   struct ThreadData {
   292    292     u8 isInit;               /* True if structure has been initialised */
   293    293     u8 mallocFailed;         /* True after a malloc() has failed */
   294    294   
   295    295   #ifndef SQLITE_OMIT_MEMORY_MANAGEMENT
   296    296     u8 useMemoryManagement;  /* True if memory-management is enabled */
   297         -  i64 nSoftHeapLimit;      /* Suggested max mem allocation.  No limit if <0 */
   298         -  i64 nAlloc;              /* Number of bytes currently allocated */
          297  +  int nSoftHeapLimit;      /* Suggested max mem allocation.  No limit if <0 */
          298  +  int nAlloc;              /* Number of bytes currently allocated */
   299    299     Pager *pPager;           /* Linked list of all pagers in this thread */
   300    300   #endif
   301    301   
   302    302   #ifndef SQLITE_OMIT_SHARED_CACHE
   303    303     u8 useSharedData;        /* True if shared pagers and schemas are enabled */
   304    304     BtShared *pBtree;        /* Linked list of all currently open BTrees */
   305    305   #endif
   306    306   
   307    307   #ifdef SQLITE_MEMDEBUG
   308         -  i64 nMaxAlloc;           /* High water mark of ThreadData.nAlloc */
          308  +  int nMaxAlloc;           /* High water mark of ThreadData.nAlloc */
   309    309     int mallocAllowed;       /* assert() in sqlite3Malloc() if not set */
   310    310     int isFail;              /* True if all malloc() calls should fail */
   311    311     const char *zFile;       /* Filename to associate debugging info with */
   312    312     int iLine;               /* Line number to associate debugging info with */
   313    313     void *pFirst;            /* Pointer to linked list of allocations */
   314    314   #endif
   315    315   };
................................................................................
   670    670   ** the column that is that key.   Otherwise Table.iPKey is negative.  Note
   671    671   ** that the datatype of the PRIMARY KEY must be INTEGER for this field to
   672    672   ** be set.  An INTEGER PRIMARY KEY is used as the rowid for each row of
   673    673   ** the table.  If a table has no INTEGER PRIMARY KEY, then a random rowid
   674    674   ** is generated for each row of the table.  Table.hasPrimKey is true if
   675    675   ** the table has any PRIMARY KEY, INTEGER or otherwise.
   676    676   **
   677         -** TODO: This comment is out of date. Table.iDb no longer exists.
   678         -**
   679    677   ** Table.tnum is the page number for the root BTree page of the table in the
   680    678   ** database file.  If Table.iDb is the index of the database table backend
   681    679   ** in sqlite.aDb[].  0 is for the main database and 1 is for the file that
   682    680   ** holds temporary tables and indices.  If Table.isTransient
   683    681   ** is true, then the table is stored in a file that is automatically deleted
   684    682   ** when the VDBE cursor to the table is closed.  In this case Table.tnum 
   685    683   ** refers VDBE cursor number that holds the table open, not to the root
................................................................................
   692    690     int nCol;        /* Number of columns in this table */
   693    691     Column *aCol;    /* Information about each column */
   694    692     int iPKey;       /* If not less then 0, use aCol[iPKey] as the primary key */
   695    693     Index *pIndex;   /* List of SQL indexes on this table. */
   696    694     int tnum;        /* Root BTree node for this table (see note above) */
   697    695     Select *pSelect; /* NULL for tables.  Points to definition if a view. */
   698    696     u8 readOnly;     /* True if this table should not be written by the user */
          697  +// u8 iDb;          /* Index into sqlite.aDb[] of the backend for this table */
   699    698     u8 isTransient;  /* True if automatically deleted when VDBE finishes */
   700    699     u8 hasPrimKey;   /* True if there exists a primary key */
   701    700     u8 keyConf;      /* What to do in case of uniqueness conflict on iPKey */
   702    701     u8 autoInc;      /* True if the integer primary key is autoincrement */
   703    702     int nRef;          /* Number of pointers to this Table */
   704    703     Trigger *pTrigger; /* List of SQL triggers on this table */
   705    704     FKey *pFKey;       /* Linked list of all foreign keys in this table */
................................................................................
   803    802   ** otherwise be equal, then return a result as if the second key
   804    803   ** were larger.
   805    804   */
   806    805   struct KeyInfo {
   807    806     u8 enc;             /* Text encoding - one of the TEXT_Utf* values */
   808    807     u8 incrKey;         /* Increase 2nd key by epsilon before comparison */
   809    808     int nField;         /* Number of entries in aColl[] */
   810         -  u8 *aSortOrder;     /* If defined and aSortOrder[i] is true, sort DESC */
          809  +  u8 *aSortOrder;     /* If defined an aSortOrder[i] is true, sort DESC */
   811    810     CollSeq *aColl[1];  /* Collating sequence for each term of the key */
   812    811   };
   813    812   
   814    813   /*
   815    814   ** Each SQL index is represented in memory by an
   816    815   ** instance of the following structure.
   817    816   **
................................................................................
   842    841     int nColumn;     /* Number of columns in the table used by this index */
   843    842     int *aiColumn;   /* Which columns are used by this index.  1st is 0 */
   844    843     unsigned *aiRowEst; /* Result of ANALYZE: Est. rows selected by each column */
   845    844     Table *pTable;   /* The SQL table being indexed */
   846    845     int tnum;        /* Page containing root of this index in database file */
   847    846     u8 onError;      /* OE_Abort, OE_Ignore, OE_Replace, or OE_None */
   848    847     u8 autoIndex;    /* True if is automatically created (ex: by UNIQUE) */
          848  +  // u8 iDb;          /* Index in sqlite.aDb[] of where this index is stored */
   849    849     char *zColAff;   /* String defining the affinity of each column */
   850    850     Index *pNext;    /* The next index associated with the same table */
   851         -  Schema *pSchema; /* Schema containing this index */
          851  +  Schema *pSchema;
   852    852     KeyInfo keyInfo; /* Info on how to order keys.  MUST BE LAST */
   853    853   };
   854    854   
   855    855   /*
   856    856   ** Each token coming out of the lexer is an instance of
   857    857   ** this structure.  Tokens are also used as part of an expression.
   858    858   **
................................................................................
   954    954   ** If the Expr is of type OP_Column, and the table it is selecting from
   955    955   ** is a disk table or the "old.*" pseudo-table, then pTab points to the
   956    956   ** corresponding table definition.
   957    957   */
   958    958   struct Expr {
   959    959     u8 op;                 /* Operation performed by this node */
   960    960     char affinity;         /* The affinity of the column or 0 if not a column */
          961  +//u8 iDb;                /* Database referenced by this expression */
   961    962     u8 flags;              /* Various flags.  See below */
   962    963     CollSeq *pColl;        /* The collation type of the column or 0 */
   963    964     Expr *pLeft, *pRight;  /* Left and right subnodes */
   964    965     ExprList *pList;       /* A list of expressions used as function arguments
   965    966                            ** or in "<expr> IN (<expr-list)" */
   966    967     Token token;           /* An operand token */
   967    968     Token span;            /* Complete text of the expression */

Changes to src/util.c.

    10     10   **
    11     11   *************************************************************************
    12     12   ** Utility functions used throughout sqlite.
    13     13   **
    14     14   ** This file contains functions for allocating memory, comparing
    15     15   ** strings, and stuff like that.
    16     16   **
    17         -** $Id: util.c,v 1.165 2006/01/10 07:14:24 danielk1977 Exp $
           17  +** $Id: util.c,v 1.166 2006/01/10 15:18:28 drh Exp $
    18     18   */
    19     19   #include "sqliteInt.h"
    20     20   #include "os.h"
    21     21   #include <stdarg.h>
    22     22   #include <ctype.h>
    23     23   
    24     24   /*
................................................................................
    67     67   #define MAX(x,y) ((x)>(y)?(x):(y))
    68     68   
    69     69   #if !defined(SQLITE_OMIT_MEMORY_MANAGEMENT) && !defined(SQLITE_OMIT_DISKIO)
    70     70   /*
    71     71   ** Set the soft heap-size limit for the current thread. Passing a negative
    72     72   ** value indicates no limit.
    73     73   */
    74         -void sqlite3_soft_heap_limit(sqlite_int64 n){
           74  +void sqlite3_soft_heap_limit(int n){
    75     75     sqlite3ThreadData()->nSoftHeapLimit = n;
    76     76   }
    77     77   
    78     78   /*
    79     79   ** Release memory held by SQLite instances created by the current thread.
    80     80   */
    81     81   int sqlite3_release_memory(int n){
................................................................................
   520    520   ** successful is returned to the caller.
   521    521   **
   522    522   ** If SQLITE_OMIT_MEMORY_MANAGEMENT is defined, this function is a no-op.
   523    523   */
   524    524   #ifndef SQLITE_OMIT_MEMORY_MANAGEMENT
   525    525   static void handleSoftLimit(int n){
   526    526     ThreadData *pTsd = sqlite3ThreadData();
   527         -  pTsd->nAlloc += (i64)n;
          527  +  pTsd->nAlloc += n;
   528    528     if( n>0 && pTsd->nSoftHeapLimit>0 ){
   529    529       while( pTsd->nAlloc>pTsd->nSoftHeapLimit && sqlite3_release_memory(n) );
   530    530     }
   531    531   }
   532    532   #else
   533    533   #define handleSoftLimit(x)
   534    534   #endif

Changes to www/capi3ref.tcl.

     1         -set rcsid {$Id: capi3ref.tcl,v 1.25 2005/12/02 01:57:43 drh Exp $}
            1  +set rcsid {$Id: capi3ref.tcl,v 1.26 2006/01/10 15:18:28 drh Exp $}
     2      2   source common.tcl
     3      3   header {C/C++ Interface For SQLite Version 3}
     4      4   puts {
     5      5   <h2>C/C++ Interface For SQLite Version 3</h2>
     6      6   }
     7      7   
     8      8   proc api {name prototype desc {notused x}} {
................................................................................
  1140   1140    the second prepared statement then all of the bindings transfered over
  1141   1141    to the second statement before the first statement is finalized.
  1142   1142   }
  1143   1143   
  1144   1144   api {} {
  1145   1145     int sqlite3_global_recover();
  1146   1146   } {
  1147         - This function is called to recover from a malloc() failure that occured
  1148         - within the SQLite library. Normally, after a single malloc() fails the 
  1149         - library refuses to function (all major calls return SQLITE_NOMEM).
  1150         - This function restores the library state so that it can be used again.
  1151         -
  1152         - All existing statements (sqlite3_stmt pointers) must be finalized or
  1153         - reset before this call is made. Otherwise, SQLITE_BUSY is returned.
  1154         - If any in-memory databases are in use, either as a main or TEMP
  1155         - database, SQLITE_ERROR is returned. In either of these cases, the 
  1156         - library is not reset and remains unusable.
  1157         -
  1158         - This function is *not* threadsafe. Calling this from within a threaded
  1159         - application when threads other than the caller have used SQLite is
  1160         - dangerous and will almost certainly result in malfunctions.
  1161         -
  1162         - This functionality can be omitted from a build by defining the 
  1163         - SQLITE_OMIT_GLOBALRECOVER at compile time.
         1147  + This function is used to be involved in recovering from out-of-memory
         1148  + errors.  But as of SQLite version 3.3.0, out-of-memory recovery is
         1149  + automatic and this routine now does nothing.  THe interface is retained
         1150  + to avoid link errors with legacy code.
  1164   1151   }
  1165   1152   
  1166   1153   api {} {
  1167   1154     int sqlite3_get_autocommit(sqlite3*);
  1168   1155   } {
  1169   1156    Test to see whether or not the database connection is in autocommit
  1170   1157    mode.  Return TRUE if it is and FALSE if not.  Autocommit mode is on
................................................................................
  1183   1170   } {
  1184   1171    Return the sqlite3* database handle to which the prepared statement given
  1185   1172    in the argument belongs.  This is the same database handle that was
  1186   1173    the first argument to the sqlite3_prepare() that was used to create
  1187   1174    the statement in the first place.
  1188   1175   }
  1189   1176   
         1177  +api {} {
         1178  +  void *sqlite3_update_hook(
         1179  +    sqlite3*, 
         1180  +    void(*)(void *,int ,char const *,char const *,sqlite_int64),
         1181  +    void*
         1182  +  );
         1183  +} {
         1184  + Register a callback function with the database connection identified by the 
         1185  + first argument to be invoked whenever a row is updated, inserted or deleted.
         1186  + Any callback set by a previous call to this function for the same 
         1187  + database connection is overridden.
         1188  +
         1189  + The second argument is a pointer to the function to invoke when a 
         1190  + row is updated, inserted or deleted. The first argument to the callback is
         1191  + a copy of the third argument to sqlite3_update_hook. The second callback 
         1192  + argument is one of SQLITE_INSERT, SQLITE_DELETE or SQLITE_UPDATE, depending
         1193  + on the operation that caused the callback to be invoked. The third and 
         1194  + fourth arguments to the callback contain pointers to the database and 
         1195  + table name containing the affected row. The final callback parameter is 
         1196  + the rowid of the row. In the case of an update, this is the rowid after 
         1197  + the update takes place.
         1198  +
         1199  + The update hook is not invoked when internal system tables are
         1200  + modified (i.e. sqlite_master and sqlite_sequence).
         1201  +
         1202  + If another function was previously registered, its pArg value is returned.
         1203  + Otherwise NULL is returned.
         1204  +
         1205  + See also: sqlite3_commit_hook(), sqlite3_rollback_hook()
         1206  +}
         1207  +
         1208  +api {} {
         1209  +  void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
         1210  +} {
         1211  + Register a callback to be invoked whenever a transaction is rolled
         1212  + back. 
         1213  +
         1214  + The new callback function overrides any existing rollback-hook
         1215  + callback. If there was an existing callback, then it's pArg value 
         1216  + (the third argument to sqlite3_rollback_hook() when it was registered) 
         1217  + is returned. Otherwise, NULL is returned.
         1218  +
         1219  + For the purposes of this API, a transaction is said to have been 
         1220  + rolled back if an explicit "ROLLBACK" statement is executed, or
         1221  + an error or constraint causes an implicit rollback to occur. The 
         1222  + callback is not invoked if a transaction is automatically rolled
         1223  + back because the database connection is closed.
         1224  +}
         1225  +
         1226  +api {} {
         1227  +  int sqlite3_enable_shared_cache(int);
         1228  +} {
         1229  +  This routine enables or disables the sharing of the database cache
         1230  +  and schema data structures between connections to the same database.
         1231  +  Sharing is enabled if the argument is true and disabled if the argument
         1232  +  is false.
         1233  +
         1234  +  Cache sharing is enabled and disabled on a thread-by-thread basis.
         1235  +  Each call to this routine enables or disables cache sharing only for
         1236  +  connections created in the same thread in which this routine is called.
         1237  +  There is no mechanism for sharing cache between database connections
         1238  +  running in different threads.
         1239  +
         1240  +  This routine must not be called when any database connections
         1241  +  are active in the current thread.  Enabling or disabling shared
         1242  +  cache while there are active database connections will result
         1243  +  in memory corruption.
         1244  +
         1245  +  For any given database connection, SQLite requires that the
         1246  +  following routines always be called from the same thread:
         1247  +  sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(),
         1248  +  sqlite3_finalize(), and sqlite3_close().  On some operating systems
         1249  +  (ex: windows and linux 2.6) you can get away with calling these routines
         1250  +  from different threads as long as their executions never overlap in time
         1251  +  and the shared cache is disabled.
         1252  +  But when the shared cache is enabled, some information about the
         1253  +  database connection is stored in thread-specific storage so that it
         1254  +  will be available for sharing with other connections.  Consequently,
         1255  +  the previously enumerated routines must always be called from the
         1256  +  same thread when shared cache is enabled, regardless of what operating
         1257  +  system is used.
         1258  +
         1259  +  This routine returns SQLITE_OK if shared cache was
         1260  +  enabled or disabled successfully.  An error code is returned
         1261  +  otherwise.
         1262  +
         1263  +  Shared cache is disabled by default for backward compatibility.
         1264  +}
         1265  +
         1266  +api {} {
         1267  +  int sqlite3_enable_memory_management(int);
         1268  +} {
         1269  +  This routine enables or disables heap memory management for the
         1270  +  thread in which it is called.  Memory management is enabled if
         1271  +  the argument is true and disabled if the argument is false.
         1272  +
         1273  +  This routine must not be called when any database connections
         1274  +  are active in the current thread.  Enabling or disabling memory
         1275  +  management while there are active database connections will result
         1276  +  in memory corruption.
         1277  +
         1278  +  When memory management is enabled, SQLite tries to automatically
         1279  +  recover from out-of-memory errors by freeing unused cache memory
         1280  +  and retrying the allocation.
         1281  +  This allows operations to continue when available memory is limit
         1282  +  though with some loss of performance due to the reduction in cache
         1283  +  size.
         1284  +
         1285  +  The sqlite3_soft_heap_limit() API can be used to restrict SQLite's
         1286  +  heap memory usage to a preset amount so that the reclamation of
         1287  +  cache begins to occur before memory is exhausted.
         1288  +
         1289  +  Memory management is enabled and disabled on a thread-by-thread basis.
         1290  +  Each call to this routine enables or disabled memory management only for
         1291  +  database connections created and used in the same thread in which this
         1292  +  routine is called.
         1293  +
         1294  +  For any given database connection, SQLite requires that the
         1295  +  following routines always be called from the same thread:
         1296  +  sqlite3_open(), sqlite3_prepare(), sqlite3_step(), sqlite3_reset(),
         1297  +  sqlite3_finalize(), and sqlite3_close().  On some operating systems
         1298  +  (ex: windows and linux 2.6) you can get away with calling these routines
         1299  +  from different threads as long as their executions never overlap in time
         1300  +  and memory management is disabled.
         1301  +  But when the memory management is enabled, some information about the
         1302  +  database connections is stored in thread-specific storage so that it
         1303  +  will be available to remediate memory shortages.  Consequently,
         1304  +  the previously enumerated routines must always be called from the
         1305  +  same thread when memory management is enabled, regardless of what
         1306  +  operating system is used.
         1307  +
         1308  +  This routine returns SQLITE_OK if the memory management module was
         1309  +  enabled or disabled successfully.  An error code is returned
         1310  +  otherwise.
         1311  +
         1312  +  Memory management is disabled by default for backwards compatibility
         1313  +  and because it is normally only useful for embedded devices.  The
         1314  +  code that implements the memory management feature can be omitted by
         1315  +  recompiling SQLite with the SQLITE_OMIT_MEMORY_MANAGEMENT macro defined.
         1316  +}
         1317  +
         1318  +api {} {
         1319  +  int sqlite3_release_memory(int N);
         1320  +} {
         1321  +  This routine attempts to free at least N bytes of memory from the caches
         1322  +  of database connecions that were created in the same thread from which this
         1323  +  routine is called.  The value returned is the number of bytes actually
         1324  +  freed.  
         1325  +
         1326  +  If memory management has not been enabled by calling
         1327  +  sqlite3_enable_memory_management() then this routine is a no-op
         1328  +  and always returns 0.
         1329  +}
         1330  +
         1331  +api {} {
         1332  +  void sqlite3_soft_heap_limit(int N);
         1333  +} {
         1334  +  This routine sets the soft heap limit for the current thread to N.
         1335  +  If memory management is enabled on the thread  by the
         1336  +  sqlite3_enable_memory_management() function and the total heap usage
         1337  +  by SQLite in that thread exceeds N, then sqlite3_release_memory() is
         1338  +  called to try to reduce the memory usage below the soft limit.
         1339  +
         1340  +  A negative value for N means that there is no soft heap limit and
         1341  +  sqlite3_release_memory() will only be called when memory is exhaused.
         1342  +  The default value for the soft heap limit is negative.
         1343  +
         1344  +  SQLite makes a best effort to honor the soft heap limit.  But if it
         1345  +  is unable to reduce memory usage below the soft limit, execution will
         1346  +  continue without error or notification.  This is way the limit is 
         1347  +  called a "soft" limit.  It is advisory only.
         1348  +
         1349  +  If memory management is not enabled, the soft heap limit is ignored.
         1350  +}
  1190   1351   
  1191   1352   set n 0
  1192   1353   set i 0
  1193   1354   foreach item $apilist {
  1194   1355     set namelist [lindex $item 0]
  1195   1356     foreach name $namelist {
  1196   1357       set n_to_name($n) $name