|
void sqlite3_soft_heap_limit(int);
The sqlite3_soft_heap_limit() interface places a "soft" limit on the amount of heap memory that may be allocated by SQLite. If an internal allocation is requested that would exceed the soft heap limit, sqlite3_release_memory() is invoked one or more times to free up some space before the allocation is performed.
The limit is called "soft", because if sqlite3_release_memory() cannot free sufficient memory to prevent the limit from being exceeded, the memory is allocated anyway and the current operation proceeds.
A negative or zero value for N means that there is no soft heap limit and sqlite3_release_memory() will only be called when memory is exhausted. The default value for the soft heap limit is zero.
SQLite makes a best effort to honor the soft heap limit. But if the soft heap limit cannot be honored, execution will continue without error or notification. This is why the limit is called a "soft" limit. It is advisory only.
Prior to SQLite version 3.5.0, this routine only constrained the memory allocated by a single thread - the same thread in which this routine runs. Beginning with SQLite version 3.5.0, the soft heap limit is applied to all threads. The value specified for the soft heap limit is an upper bound on the total memory allocation for all threads. In version 3.5.0 there is no mechanism for limiting the heap usage for individual threads.
H16351 | The sqlite3_soft_heap_limit(N) interface places a soft limit of N bytes on the amount of heap memory that may be allocated using sqlite3_malloc() or sqlite3_realloc() at any point in time. |
H16352 | If a call to sqlite3_malloc() or sqlite3_realloc() would cause the total amount of allocated memory to exceed the soft heap limit, then sqlite3_release_memory() is invoked in an attempt to reduce the memory usage prior to proceeding with the memory allocation attempt. |
H16353 | Calls to sqlite3_malloc() or sqlite3_realloc() that trigger attempts to reduce memory usage through the soft heap limit mechanism continue even if the attempt to reduce memory usage is unsuccessful. |
H16354 | A negative or zero value for N in a call to sqlite3_soft_heap_limit(N) means that there is no soft heap limit and sqlite3_release_memory() will only be called when memory is completely exhausted. |
H16355 | The default value for the soft heap limit is zero. |
H16358 | Each call to sqlite3_soft_heap_limit(N) overrides the values set by all prior calls. |
See also lists of Objects, Constants, and Functions.