Documentation Source Text

Check-in [5d170249d2]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to the documentation for the new sqlite3_soft_heap_limit64() interface.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5d170249d27d3ac04f23ae7556ccd9d151f4c3b7
User & Date: drh 2010-09-15 22:17:34
Context
2010-09-16
18:50
Change the documentation for LIMIT and OFFSET clauses to be more testable. check-in: 1cb27a268e user: dan tags: trunk
2010-09-15
22:17
Updates to the documentation for the new sqlite3_soft_heap_limit64() interface. check-in: 5d170249d2 user: drh tags: trunk
18:54
Changes to make the documentation for ORDER BY more testable. check-in: 095cad2463 user: dan tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

46
47
48
49
50
51
52
53
54


55
56
57
58
59
60
61
<li> Added the [sqlite3_create_function_v2()] interface that includes a
     destructor callback.
<li> Added support for [custom r-tree queries] using application-supplied
     callback routines to define the boundary of the query region.
<li> The default page cache strives more diligently to avoid using memory
     beyond what is allocated to it by [SQLITE_CONFIG_PAGECACHE].  Or if
     using page cache is allocating from the heap, it strives to avoid
     going over the [sqlite3_soft_heap_limit()], even if
     [SQLITE_ENABLE_MEMORY_MANAGEMENT] is not set.


}

chng {2010 August 24 (3.7.2)} {
<li> Fix an <a href="http://www.sqlite.org/src/info/5e10420e8d">
     old and very obscure bug</a> that can lead to corruption of the
     database [free-page list] when [incremental_vacuum] is used.
}







|

>
>







46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
<li> Added the [sqlite3_create_function_v2()] interface that includes a
     destructor callback.
<li> Added support for [custom r-tree queries] using application-supplied
     callback routines to define the boundary of the query region.
<li> The default page cache strives more diligently to avoid using memory
     beyond what is allocated to it by [SQLITE_CONFIG_PAGECACHE].  Or if
     using page cache is allocating from the heap, it strives to avoid
     going over the [sqlite3_soft_heap_limit64()], even if
     [SQLITE_ENABLE_MEMORY_MANAGEMENT] is not set.
<li> Added the [sqlite3_soft_heap_limit64()] interface as a replacement for
     [sqlite3_soft_heap_limit()].
}

chng {2010 August 24 (3.7.2)} {
<li> Fix an <a href="http://www.sqlite.org/src/info/5e10420e8d">
     old and very obscure bug</a> that can lead to corruption of the
     database [free-page list] when [incremental_vacuum] is used.
}

Changes to pages/compile.in.

351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
}

COMPILE_OPTION {SQLITE_ENABLE_MEMORY_MANAGEMENT} {
  This option adds extra logic to SQLite that allows it to release unused
  memory upon request.  This option must be enabled in order for the
  [sqlite3_release_memory()] interface to work.  If this compile-time
  option is not used, the [sqlite3_release_memory()] interface is a 
  no-op.  Since [sqlite3_soft_heap_limit()] depends on
  [sqlite3_release_memory()], this option is also necessary for
  the correct operation of [sqlite3_soft_heap_limit()].
}

COMPILE_OPTION {SQLITE_ENABLE_MEMSYS3} {
  This option includes code in SQLite that implements an alternative
  memory allocator.  This alternative memory allocator is only engaged
  when the [SQLITE_CONFIG_HEAP] option to [sqlite3_config()] is used to
  supply a large chunk of memory from which all memory allocations are







|
<
<







351
352
353
354
355
356
357
358


359
360
361
362
363
364
365
}

COMPILE_OPTION {SQLITE_ENABLE_MEMORY_MANAGEMENT} {
  This option adds extra logic to SQLite that allows it to release unused
  memory upon request.  This option must be enabled in order for the
  [sqlite3_release_memory()] interface to work.  If this compile-time
  option is not used, the [sqlite3_release_memory()] interface is a 
  no-op.


}

COMPILE_OPTION {SQLITE_ENABLE_MEMSYS3} {
  This option includes code in SQLite that implements an alternative
  memory allocator.  This alternative memory allocator is only engaged
  when the [SQLITE_CONFIG_HEAP] option to [sqlite3_config()] is used to
  supply a large chunk of memory from which all memory allocations are

Changes to pages/custombuild.in.

150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
The second [SQLITE_CONFIG_MEMSTATUS] setting disables the mechanism
in SQLite that tracks the total size of all outstanding memory
allocation requests.  This omits the need to mutex each call
to [sqlite3_malloc()] and [sqlite3_free()], which saves a huge
number of mutex operations.  But a consequence of disabling the
memory statistics mechanism is that the 
[sqlite3_memory_used()], [sqlite3_memory_highwater()], and
[sqlite3_soft_heap_limit()] interfaces cease to work.
</p>

<p>SQLite uses pthreads for its mutex implementation on Unix and
SQLite requires a recursive mutex.  Most modern pthread implementations
support recursive mutexes, but not all do.  For systems that do not
support recursive mutexes, it is recommended that applications operate
in single-threaded mode only.  If this is not possible, SQLite provides







|







150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
The second [SQLITE_CONFIG_MEMSTATUS] setting disables the mechanism
in SQLite that tracks the total size of all outstanding memory
allocation requests.  This omits the need to mutex each call
to [sqlite3_malloc()] and [sqlite3_free()], which saves a huge
number of mutex operations.  But a consequence of disabling the
memory statistics mechanism is that the 
[sqlite3_memory_used()], [sqlite3_memory_highwater()], and
[sqlite3_soft_heap_limit64()] interfaces cease to work.
</p>

<p>SQLite uses pthreads for its mutex implementation on Unix and
SQLite requires a recursive mutex.  Most modern pthread implementations
support recursive mutexes, but not all do.  For systems that do not
support recursive mutexes, it is recommended that applications operate
in single-threaded mode only.  If this is not possible, SQLite provides

Changes to pages/malloc.in.

48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
the application cooperates, SQLite will never leak memory.  This is
true even in the face of memory allocation failures or other system
errors.
</p></li>

<li><p>
<b>Memory usage limits.</b>
The [sqlite3_soft_heap_limit()] mechanism allows the application to
set a memory usage limit that SQLite strives to stay below.  SQLite
will attempt to reuse memory from its caches rather than allocation new
memory as it approaches the soft limit.
</p></li>

<li><p>
<b>Zero-malloc option</b>







|







48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
the application cooperates, SQLite will never leak memory.  This is
true even in the face of memory allocation failures or other system
errors.
</p></li>

<li><p>
<b>Memory usage limits.</b>
The [sqlite3_soft_heap_limit64()] mechanism allows the application to
set a memory usage limit that SQLite strives to stay below.  SQLite
will attempt to reuse memory from its caches rather than allocation new
memory as it approaches the soft limit.
</p></li>

<li><p>
<b>Zero-malloc option</b>