1.Dd January 24, 2024 2.Dt SQLITE3_SOFT_HEAP_LIMIT64 3 3.Os 4.Sh NAME 5.Nm sqlite3_soft_heap_limit64 , 6.Nm sqlite3_hard_heap_limit64 7.Nd impose a limit on heap size 8.Sh SYNOPSIS 9.In sqlite3.h 10.Ft sqlite3_int64 11.Fo sqlite3_soft_heap_limit64 12.Fa "sqlite3_int64 N" 13.Fc 14.Ft sqlite3_int64 15.Fo sqlite3_hard_heap_limit64 16.Fa "sqlite3_int64 N" 17.Fc 18.Sh DESCRIPTION 19These interfaces impose limits on the amount of heap memory that will 20be by all database connections within a single process. 21.Pp 22The sqlite3_soft_heap_limit64() interface sets and/or queries the soft 23limit on the amount of heap memory that may be allocated by SQLite. 24SQLite strives to keep heap memory utilization below the soft heap 25limit by reducing the number of pages held in the page cache as heap 26memory usages approaches the limit. 27The soft heap limit is "soft" because even though SQLite strives to 28stay below the limit, it will exceed the limit rather than generate 29an SQLITE_NOMEM error. 30In other words, the soft heap limit is advisory only. 31.Pp 32The sqlite3_hard_heap_limit64(N) interface sets a hard upper bound 33of N bytes on the amount of memory that will be allocated. 34The sqlite3_hard_heap_limit64(N) interface is similar to sqlite3_soft_heap_limit64(N) 35except that memory allocations will fail when the hard heap limit is 36reached. 37.Pp 38The return value from both sqlite3_soft_heap_limit64() and sqlite3_hard_heap_limit64() 39is the size of the heap limit prior to the call, or negative in the 40case of an error. 41If the argument N is negative then no change is made to the heap limit. 42Hence, the current size of heap limits can be determined by invoking 43sqlite3_soft_heap_limit64(-1) or sqlite3_hard_heap_limit(-1). 44.Pp 45Setting the heap limits to zero disables the heap limiter mechanism. 46.Pp 47The soft heap limit may not be greater than the hard heap limit. 48If the hard heap limit is enabled and if sqlite3_soft_heap_limit(N) 49is invoked with a value of N that is greater than the hard heap limit, 50the soft heap limit is set to the value of the hard heap limit. 51The soft heap limit is automatically enabled whenever the hard heap 52limit is enabled. 53When sqlite3_hard_heap_limit64(N) is invoked and the soft heap limit 54is outside the range of 1..N, then the soft heap limit is set to N. 55Invoking sqlite3_soft_heap_limit64(0) when the hard heap limit is enabled 56makes the soft heap limit equal to the hard heap limit. 57.Pp 58The memory allocation limits can also be adjusted using PRAGMA soft_heap_limit 59and PRAGMA hard_heap_limit. 60.Pp 61The heap limits are not enforced in the current implementation if one 62or more of following conditions are true: 63.Bl -bullet 64.It 65The limit value is set to zero. 66.It 67Memory accounting is disabled using a combination of the sqlite3_config(SQLITE_CONFIG_MEMSTATUS,...) 68start-time option and the SQLITE_DEFAULT_MEMSTATUS 69compile-time option. 70.It 71An alternative page cache implementation is specified using sqlite3_config(SQLITE_CONFIG_PCACHE2,...). 72.It 73The page cache allocates from its own memory pool supplied by sqlite3_config(SQLITE_CONFIG_PAGECACHE,...) 74rather than from the heap. 75.El 76.Pp 77The circumstances under which SQLite will enforce the heap limits may 78changes in future releases of SQLite. 79.Sh IMPLEMENTATION NOTES 80These declarations were extracted from the 81interface documentation at line 6969. 82.Bd -literal 83SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N); 84SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N); 85.Ed 86.Sh SEE ALSO 87.Xr sqlite3_config 3 , 88.Xr SQLITE_CONFIG_SINGLETHREAD 3 , 89.Xr SQLITE_OK 3 90