1.Dd March 11, 2017 2.Dt SQLITE3_SOFT_HEAP_LIMIT64 3 3.Os 4.Sh NAME 5.Nm sqlite3_soft_heap_limit64 6.Nd Impose A Limit On Heap Size 7.Sh SYNOPSIS 8.Ft sqlite3_int64 9.Fo sqlite3_soft_heap_limit64 10.Fa "sqlite3_int64 N" 11.Fc 12.Sh DESCRIPTION 13The sqlite3_soft_heap_limit64() interface sets and/or queries the soft 14limit on the amount of heap memory that may be allocated by SQLite. 15SQLite strives to keep heap memory utilization below the soft heap 16limit by reducing the number of pages held in the page cache as heap 17memory usages approaches the limit. 18The soft heap limit is "soft" because even though SQLite strives to 19stay below the limit, it will exceed the limit rather than generate 20an SQLITE_NOMEM error. 21In other words, the soft heap limit is advisory only. 22.Pp 23The return value from sqlite3_soft_heap_limit64() is the size of the 24soft heap limit prior to the call, or negative in the case of an error. 25If the argument N is negative then no change is made to the soft heap 26limit. 27Hence, the current size of the soft heap limit can be determined by 28invoking sqlite3_soft_heap_limit64() with a negative argument. 29.Pp 30If the argument N is zero then the soft heap limit is disabled. 31.Pp 32The soft heap limit is not enforced in the current implementation if 33one or more of following conditions are true: 34.Bl -bullet 35.It 36The soft heap limit is set to zero. 37.It 38Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) 39start-time option and the SQLITE_DEFAULT_MEMSTATUS 40compile-time option. 41.It 42An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE2,...). 43.It 44The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) 45rather than from the heap. 46.El 47.Pp 48Beginning with SQLite version 3.7.3 (dateof:3.7.3), 49the soft heap limit is enforced regardless of whether or not the SQLITE_ENABLE_MEMORY_MANAGEMENT 50compile-time option is invoked. 51With SQLITE_ENABLE_MEMORY_MANAGEMENT, 52the soft heap limit is enforced on every memory allocation. 53Without SQLITE_ENABLE_MEMORY_MANAGEMENT, 54the soft heap limit is only enforced when memory is allocated by the 55page cache. 56Testing suggests that because the page cache is the predominate memory 57user in SQLite, most applications will achieve adequate soft heap limit 58enforcement without the use of SQLITE_ENABLE_MEMORY_MANAGEMENT. 59.Pp 60The circumstances under which SQLite will enforce the soft heap limit 61may changes in future releases of SQLite. 62.Sh SEE ALSO 63.Xr sqlite3_config 3 , 64.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 65.Xr SQLITE_OK 3 66