Sq3Lite_Internal_Memory_C_API

Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' … More...

Collaboration diagram for Sq3Lite_Internal_Memory_C_API:

Functions
static MK_I64	Sq3HardHeapLimit64 (MK_I64 N)
	Impose A Limit On Heap Size …
static enum MkErrorE	Sq3ReleaseMemory (MK_I32 N)
	Attempt To Free Heap Memory …
static MK_I64	Sq3SoftHeapLimit64 (MK_I64 N)
	Impose A Limit On Heap Size …

Sq3Lite - Sq3Lite_Internal_Memory_C_API - function
MK_I64	Sq3HardHeapLimit64P (MK_I64 N)
	Non-inline replacement for Sq3HardHeapLimit64 …
enum MkErrorE	Sq3ReleaseMemoryP (MK_I32 N)
	Non-inline replacement for Sq3ReleaseMemory …
MK_I64	Sq3SoftHeapLimit64P (MK_I64 N)
	Non-inline replacement for Sq3SoftHeapLimit64 …

Sq3Lite - Sq3Lite_Internal_Memory_C_API - overload
#define	Sq3ReleaseMemory_E(...)
#define	Sq3ReleaseMemory_C(...)

Detailed Description

Sq3Lite PACKAGE - functions related to index 'Internal' and doc 'Memory' …

Attempt To Free Heap Memory:

• Sq3ReleaseMemory

Impose A Limit On Heap Size:

• Sq3HardHeapLimit64
• Sq3SoftHeapLimit64

Reference code from sqlite3:

// Attempt To Free Heap Memory:
SQLITE_API int sqlite3_release_memory(int);
 
// Impose A Limit On Heap Size:
SQLITE_API sqlite3_int64 sqlite3_soft_heap_limit64(sqlite3_int64 N);
SQLITE_API sqlite3_int64 sqlite3_hard_heap_limit64(sqlite3_int64 N);

Macro Definition Documentation

Sq3ReleaseMemory_C

#define Sq3ReleaseMemory_C

(

...

)

Value:

if (MkErrorCheckI(Sq3ReleaseMemory(__VA_ARGS__)))

Definition at line 281 of file sqlite3_overload_sq3.h.

Sq3ReleaseMemory_E

#define Sq3ReleaseMemory_E

(

...

)

Value:

MkErrorCheck(Sq3ReleaseMemory(__VA_ARGS__))

Definition at line 280 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3HardHeapLimit64()

static MK_I64 Sq3HardHeapLimit64 ( MK_I64 N )

inlinestatic

Impose A Limit On Heap Size …

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

The Sq3SoftHeapLimit64() interface sets and/or queries the soft limit on the amount of heap memory that may be allocated by SQLite. 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. 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 SQ3_RESULT_NOMEM error. In other words, the soft heap limit is advisory only.

The Sq3HardHeapLimit64(N) interface sets a hard upper bound of N bytes on the amount of memory that will be allocated. The Sq3HardHeapLimit64(N) interface is similar to Sq3SoftHeapLimit64(N) except that memory allocations will fail when the hard heap limit is reached.

The return value from both Sq3SoftHeapLimit64() and Sq3HardHeapLimit64() is the size of the heap limit prior to the call, or negative in the case of an error. 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 Sq3SoftHeapLimit64(-1) or Sq3HardHeapLimit64(-1).

Setting the heap limits to zero disables the heap limiter mechanism.

The soft heap limit may not be greater than the hard heap limit. 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. The soft heap limit is automatically enabled whenever the hard heap limit is enabled. When Sq3HardHeapLimit64(N) is invoked and the soft heap limit is outside the range of 1..N, then the soft heap limit is set to N. Invoking Sq3SoftHeapLimit64(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.

The heap limits are not enforced in the current implementation if one or more of following conditions are true:

• The limit value is set to zero.
• Memory accounting is disabled using a combination of the sqlite3_config(SQ3_CONFIG_MEMSTATUS,...) start-time option and the SQLITE_DEFAULT_MEMSTATUS compile-time option.
• An alternative page cache implementation is specified using sqlite3_config(SQ3_CONFIG_PCACHE2,...).
• The page cache allocates from its own memory pool supplied by sqlite3_config(SQ3_CONFIG_PAGECACHE,...) rather than from the heap.

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

Reference code from sqlite3:

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

Definition at line 800 of file LibSq3Lite_sq3.h.

                                                 {
    return sqlite3_hard_heap_limit64(N);
  }

Here is the caller graph for this function:

Sq3HardHeapLimit64P()

MK_I64 Sq3HardHeapLimit64P

(

MK_I64

N

)

Non-inline replacement for Sq3HardHeapLimit64 …

Sq3ReleaseMemory()

static enum MkErrorE Sq3ReleaseMemory ( MK_I32 N )

inlinestatic

Attempt To Free Heap Memory …

The Sq3ReleaseMemory() interface attempts to free N bytes of heap memory by deallocating non-essential memory allocations held by the database library. Memory used to cache database pages to improve performance is an example of non-essential memory. Sq3ReleaseMemory() returns the number of bytes actually freed, which might be more or less than the amount requested. The Sq3ReleaseMemory() routine is a no-op returning zero if SQLite is not compiled with SQLITE_ENABLE_MEMORY_MANAGEMENT.

See also: Sq3LiteDbReleaseMemory ()

Reference code from sqlite3:

SQLITE_API int sqlite3_release_memory(int);

Definition at line 805 of file LibSq3Lite_sq3.h.

                                                      {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_release_memory(N);
    Sq3ErrorE_Check_Package(errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3ReleaseMemoryP()

enum MkErrorE Sq3ReleaseMemoryP

(

MK_I32

N

)

Non-inline replacement for Sq3ReleaseMemory …

Sq3SoftHeapLimit64()

static MK_I64 Sq3SoftHeapLimit64 ( MK_I64 N )

inlinestatic

Impose A Limit On Heap Size …

read more at 'Sq3HardHeapLimit64'

Definition at line 814 of file LibSq3Lite_sq3.h.

                                                 {
    return sqlite3_soft_heap_limit64(N);
  }

Here is the caller graph for this function:

Sq3SoftHeapLimit64P()

MK_I64 Sq3SoftHeapLimit64P

(

MK_I64

N

)

Non-inline replacement for Sq3SoftHeapLimit64 …