*** DRAFT ***

SQLite C Interface

Impose A Limit On Heap Size

sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);

These interfaces impose limits on the amount of heap memory that will be by all database connections within a single process.

R-54493-30181:[The sqlite3_soft_heap_limit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. ] R-27925-06263:[SQLite strives to keep heap memory utilization below the soft heap limit by reducing the number of pages held in the page cache as heap memory usages approaches the limit. ] R-54035-60779:[The soft heap limit is "soft" because even though SQLite strives to stay below the limit, it will exceed the limit rather than generate an SQLITE_NOMEM error. ] In other words, the soft heap limit is advisory only.

R-53924-42297:[The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound of N bytes on the amount of memory that will be allocated. ] R-36882-08642:[The sqlite3_hard_heap_limit64(N) interface is similar to sqlite3_soft_heap_limit64(N) except that memory allocations will fail when the hard heap limit is reached. ]

R-57611-29319:[The return value from both sqlite3_soft_heap_limit64() and sqlite3_hard_heap_limit64() is the size of the heap limit prior to the call, or negative in the case of an error. ] R-06730-45014:[If the argument N is negative then no change is made to the heap limit. ] Hence, the current size of heap limits can be determined by invoking sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1).

R-42053-10634:[Setting the heap limits to zero disables the heap limiter mechanism. ]

R-52858-40376:[The soft heap limit may not be greater than the hard heap limit. ] R-48588-03878:[If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) is invoked with a value of N that is greater than the hard heap limit, the soft heap limit is set to the value of the hard heap limit. ] R-14928-00869:[The soft heap limit is automatically enabled whenever the hard heap limit is enabled. ] R-21205-43338:[When sqlite3_hard_heap_limit64(N) is invoked and the soft heap limit is outside the range of 1. ] .N, then the soft heap limit is set to N. R-50479-29416:[Invoking sqlite3_soft_heap_limit64(0) when the hard heap limit is enabled makes the soft heap limit equal to the hard heap limit. ]

The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit and PRAGMA hard_heap_limit.

R-02230-09674:[The heap limits are not enforced in the current implementation if one or more of following conditions are true:

]

The circumstances under which SQLite will enforce the heap limits may changes in future releases of SQLite.

See also lists of Objects, Constants, and Functions.

*** DRAFT ***