1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
3
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
4
<title>Dynamic Memory Allocation In SQLite</title>
5
<style type="text/css">
8
font-family: Verdana, sans-serif;
13
a:visited { color: #734559 }
15
.logo { position:absolute; margin:3px; }
31
.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }
32
.toolbar a:visited { color: white; }
33
.toolbar a:hover { color: #044a64; background: white; }
35
.content { margin: 5%; }
36
.content dt { font-weight:bold; }
37
.content dd { margin-bottom: 25px; margin-left:20%; }
38
.content ul { padding:0px; padding-left: 15px; margin:0px; }
41
.se { background: url(images/se.gif) 100% 100% no-repeat #044a64}
42
.sw { background: url(images/sw.gif) 0% 100% no-repeat }
43
.ne { background: url(images/ne.gif) 100% 0% no-repeat }
44
.nw { background: url(images/nw.gif) 0% 0% no-repeat }
46
/* Things for "fancyformat" documents start here. */
47
.fancy img+p {font-style:italic}
48
.fancy .codeblock i { color: darkblue; }
49
.fancy h1,.fancy h2,.fancy h3,.fancy h4 {font-weight:normal;color:#044a64}
50
.fancy h2 { margin-left: 10px }
51
.fancy h3 { margin-left: 20px }
52
.fancy h4 { margin-left: 30px }
53
.fancy th {white-space:nowrap;text-align:left;border-bottom:solid 1px #444}
54
.fancy th, .fancy td {padding: 0.2em 1ex; vertical-align:top}
55
.fancy #toc a { color: darkblue ; text-decoration: none }
56
.fancy .todo { color: #AA3333 ; font-style : italic }
57
.fancy .todo:before { content: 'TODO:' }
58
.fancy p.todo { border: solid #AA3333 1px; padding: 1ex }
59
.fancy img { display:block; }
60
.fancy :link:hover, .fancy :visited:hover { background: wheat }
61
.fancy p,.fancy ul,.fancy ol { margin: 1em 5ex }
62
.fancy li p { margin: 1em 0 }
63
/* End of "fancyformat" specific rules. */
69
<div><!-- container div to satisfy validator -->
72
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite Logo"
74
<div><!-- IE hack to prevent disappearing logo--></div>
75
<div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div>
77
<table width=100% style="clear:both"><tr><td>
78
<div class="se"><div class="sw"><div class="ne"><div class="nw">
79
<table width=100% style="padding:0;margin:0;cell-spacing:0"><tr>
82
<a href="about.html">About</a>
83
<a href="sitemap.html">Sitemap</a>
84
<a href="docs.html">Documentation</a>
85
<a href="download.html">Download</a>
86
<a href="copyright.html">License</a>
87
<a href="news.html">News</a>
88
<a href="support.html">Support</a>
91
gMsg = "Search SQLite Docs..."
92
function entersearch() {
93
var q = document.getElementById("q");
94
if( q.value == gMsg ) { q.value = "" }
95
q.style.color = "black"
96
q.style.fontStyle = "normal"
98
function leavesearch() {
99
var q = document.getElementById("q");
100
if( q.value == "" ) {
102
q.style.color = "#044a64"
103
q.style.fontStyle = "italic"
108
<div style="padding:0 1em 0px 0;white-space:nowrap">
109
<form name=f method="GET" action="http://www.sqlite.org/search">
110
<input id=q name=q type=text
111
onfocus="entersearch()" onblur="leavesearch()" style="width:24ex;padding:1px 1ex; border:solid white 1px; font-size:0.9em ; font-style:italic;color:#044a64;" value="Search SQLite Docs...">
112
<input type=submit value="Go" style="border:solid white 1px;background-color:#044a64;color:white;font-size:0.9em;padding:0 1ex">
116
</div></div></div></div>
118
<div class=startsearch></div>
122
<h1>Dynamic Memory Allocation In SQLite</h1>
125
<p>SQLite uses dynamic memory allocation to obtain
126
memory for storing various objects
127
(ex: <a href="c3ref/sqlite3.html">database connections</a> and <a href="c3ref/stmt.html">prepared statements</a>) and to build
128
a memory cache of the database file and to hold the results of queries.
129
Much effort has gone into making the dynamic memory allocation subsystem
130
of SQLite reliable, predictable, robust, and efficient.</p>
132
<p>This document provides an overview of dynamic memory allocation within
133
SQLite. The target audience is software engineers who are tuning their
134
use of SQLite for peak performance in demanding environments.
135
Nothing in this document is required knowledge for using SQLite. The
136
default settings and configuration for SQLite will work well in most
137
applications. However, the information contained in this document may
138
be useful to engineers who are tuning SQLite to comply with special
139
requirements or to run under unusual circumstances.</p>
141
<a name="features"></a>
142
<h2>1.0 Features</h2>
144
<p>The SQLite core and its memory allocation subsystem provides the
145
following capabilities:</p>
149
<b>Robust against allocation failures.</b>
150
If a memory allocation ever fails (that is to say,
151
if malloc() or realloc() ever return NULL)
152
then SQLite will recover gracefully. SQLite will first attempt
153
to free memory from unpinned cache pages then retry the allocation
155
Failing that, SQLite will either stop what
156
it is doing and return the
157
<a href="c3ref/c_abort.html">SQLITE_NOMEM</a> error code back up to the application or it will
158
make do without the requested memory.
162
<b>No memory leaks.</b>
163
The application is responsible for destroying any objects it allocates.
164
(For example, the application must use <a href="c3ref/finalize.html">sqlite3_finalize()</a> on
165
every <a href="c3ref/stmt.html">prepared statement</a> and <a href="c3ref/close.html">sqlite3_close()</a> on every
166
<a href="c3ref/sqlite3.html">database connection</a>.) But as long as
167
the application cooperates, SQLite will never leak memory. This is
168
true even in the face of memory allocation failures or other system
173
<b>Memory usage limits.</b>
174
The <a href="c3ref/soft_heap_limit64.html">sqlite3_soft_heap_limit64()</a> mechanism allows the application to
175
set a memory usage limit that SQLite strives to stay below. SQLite
176
will attempt to reuse memory from its caches rather than allocation new
177
memory as it approaches the soft limit.
181
<b>Zero-malloc option</b>
182
The application can provide SQLite with several buffers of bulk memory
183
at startup and SQLite will then use those provided buffers for all of
184
its memory allocation needs and never call system malloc() or free().
188
<b>Application-supplied memory allocators.</b>
189
The application can provide SQLite with pointers to alternative
190
memory allocators at start-time. The alternative memory allocator
191
will be used in place of system malloc() and free().
195
<b>Proof against breakdown and fragmentation.</b>
196
SQLite can be configured so that, subject to certain usage constraints
197
detailed below, it is guaranteed to never fail a memory allocation
198
or fragment the heap.
199
This property is important to long-running, high-reliability
200
embedded systems where a memory allocation error could contribute
201
to an overall system failure.
205
<b>Memory usage statistics.</b>
206
Applications can see how much memory they are using and detect when
207
memory usage is approaching or exceeding design boundaries.
211
<b>Minimal calls to the allocator.</b>
212
The system malloc() and free() implementations are inefficient
213
on many systems. SQLite strives to reduce overall processing time
214
by minimizing its use of malloc() and free().
219
Pluggable SQLite extensions or even the application itself can
220
access to the same underlying memory allocation
221
routines used by SQLite through the
222
<a href="c3ref/free.html">sqlite3_malloc()</a>, <a href="c3ref/free.html">sqlite3_realloc()</a>, and <a href="c3ref/free.html">sqlite3_free()</a> interfaces.
227
<a name="testing"></a>
231
75% of the code in the SQLite source tree is devoted purely to
232
<a href="testing.html">testing and verification</a>. Reliability is important to SQLite.
233
Among the tasks of the test infrastructure is to ensure that
234
SQLite does not misuse dynamically allocated memory, that SQLite
235
does not leak memory, and that SQLite responds
236
correctly to a dynamic memory allocation failure.</p>
238
<p>The test infrastructure verifies that SQLite does not misuse
239
dynamically allocated memory by using a specially instrumented
240
memory allocator. The instrumented memory allocator is enabled
241
at compile-time using the <a href="compile.html#memdebug">SQLITE_MEMDEBUG</a> option. The instrumented
242
memory allocator is much slower than the default memory allocator and
243
so its use is not recommended in production. But when
244
enabled during testing,
245
the instrumented memory allocator performs the following checks:</p>
248
<li><p><b>Bounds checking.</b>
249
The instrumented memory allocator places sentinel values at both ends
250
of each memory allocation to verify that nothing within SQLite writes
251
outside the bounds of the allocation.</p></li>
253
<li><p><b>Use of memory after freeing.</b>
254
When each block of memory is freed, every byte is overwritten with a
255
nonsense bit pattern. This helps to ensure that no memory is ever
256
used after having been freed.</p></li>
258
<li><p><b>Freeing memory not obtained from malloc.</b>
259
Each memory allocation from the instrumented memory allocator contains
260
sentinels used to verify that every allocation freed came
261
from prior malloc.</p></li>
263
<li><p><b>Uninitialized memory.</b>
264
The instrumented memory allocator initializes each memory allocation
265
to a nonsense bit pattern to help ensure that the user makes no
266
assumptions about the content of allocation memory.</p></li>
269
<p>Regardless of whether or not the instrumented memory allocator is
270
used, SQLite keeps track of how much memory is currently checked out.
271
There are hundreds of test scripts used for testing SQLite. At the
272
end of each script, all objects are destroyed and a test is made to
273
ensure that all memory has been freed. This is how memory
274
leaks are detected. Notice that memory leak detection is in force at
275
all times, during test builds and during production builds. Whenever
276
one of the developers runs any individual test script, memory leak
277
detection is active. Hence memory leaks that do arise during development
278
are quickly detected and fixed.</p>
280
<a name="oomtesting"></a>
281
<p>The response of SQLite to out-of-memory (OOM) errors is tested using
282
a specialized memory allocator overlay that can simulate memory failures.
283
The overlay is a layer that is inserted in between the memory allocator
284
and the rest of SQLite. The overlay passes most memory allocation
285
requests straight through to the underlying allocator and passes the
286
results back up to the requester. But the overlay can be set to
287
cause the Nth memory allocation to fail. To run an OOM test, the overlay
288
is first set to fail on the first allocation attempt. Then some test
289
script is run and verification that the allocation was correctly caught
290
and handled is made. Then the overlay is set to fail on the second
291
allocation and the test repeats. The failure point continues to advice
292
one allocation at a time until the entire test procedure runs to
293
completion without hitting a memory allocation error. This whole
294
test sequence run twice. On the first pass, the
295
overlay is set to fail only the Nth allocation. On the second pass,
296
the overlay is set to fail the Nth and all subsequent allocations.</p>
298
<p>Note that the memory leak detection logic continues to work even
299
when the OOM overlay is being used. This verifies that SQLite
300
does not leak memory even when it encounters memory allocation errors.
301
Note also that the OOM overlay can work with any underlying memory
302
allocator, including the instrumented memory allocator that checks
303
for memory allocation misuse. In this way it is verified that
304
OOM errors do not induce other kinds of memory usage errors.</p>
306
<p>Finally, we observe that the instrumented memory allocator and the
307
memory leak detector both work over the entire SQLite test suite and
308
the <a href="testing.html#tcl">TCL test suite</a> provides over 99% statement test coverage and that
309
the <a href="th3.html">TH3</a> test harness provides <a href="testing.html#coverage">100% branch test coverage</a>
310
with no leak leaks. This is
311
strong evidence that dynamic memory allocation is used correctly
312
everywhere within SQLite.</p>
314
<a name="config"></a>
315
<h2>3.0 Configuration</h2>
317
<p>The default memory allocation settings in SQLite are appropriate
318
for most applications. However, applications with unusual or particularly
319
strict requirements may want to adjust the configuration to more closely
320
align SQLite to their needs.
321
Both compile-time and start-time configuration options are available.</p>
323
<a name="altalloc"></a>
325
<h3>3.1 Alternative low-level memory allocators</h3>
327
<p>The SQLite source code includes several different memory allocation
328
modules that can be selected at compile-time, or to a limited extent
331
<a name="defaultalloc"></a>
333
<h4>3.1.1 The default memory allocator</h4>
335
<p>By default, SQLite uses the malloc(), realloc(), and free() routines
336
from the standard C library for its memory allocation needs. These routines
337
are surrounded by a thin wrapper that also provides a "memsize()" function
338
that will return the size of an existing allocation. The memsize() function
339
is needed to keep an accurate count of the number of bytes of outstanding
340
memory; memsize() determines how many bytes to remove from the outstanding
341
count when an allocation is freed. The default allocator implements
342
memsize() by always allocating 8 extra bytes on each malloc() request and
343
storing the size of the allocation in that 8-byte header.</p>
345
<p>The default memory allocator is recommended for most applications.
346
If you do not have a compelling need to use an alternative memory
347
allocator, then use the default.</p>
349
<a name="memdebug"></a>
351
<h4>3.1.2 The debugging memory allocator</h4>
353
<p>If SQLite is compiled with the <a href="compile.html#memdebug">SQLITE_MEMDEBUG</a> compile-time option,
354
then a different, heavy wrapper is used around system malloc(), realloc(),
356
The heavy wrapper allocates around 100 bytes of extra space
357
with each allocation. The extra space is used to place sentinel values
358
at both ends of the allocation returned to the SQLite core. When an
360
these sentinels are checked to make sure the SQLite core did not overrun
361
the buffer in either direction. When the system library is GLIBC, the
362
heavy wrapper also makes use of the GNU backtrace() function to examine
363
the stack and record the ancestor functions of the malloc() call. When
364
running the SQLite test suite, the heavy wrapper also records the name of
365
the current test case. These latter two features are useful for
366
tracking down the source of memory leaks detected by the test suite.</p>
368
<p>The heavy wrapper that is used when <a href="compile.html#memdebug">SQLITE_MEMDEBUG</a> is set also
369
makes sure each new allocation is filled with nonsense data prior to
370
returning the allocation to the caller. And as soon as an allocation
371
is free, it is again filled with nonsense data. These two actions help
372
to ensure that the SQLite core does not make assumptions about the state
373
of newly allocated memory and that memory allocations are not used after
374
they have been freed.</p>
376
<p>The heavy wrapper employed by <a href="compile.html#memdebug">SQLITE_MEMDEBUG</a> is intended for use
377
only during testing, analysis, and debugging of SQLite. The heavy wrapper
378
has a significant performance and memory overhead and probably should not
379
be used in production.</p>
381
<a name="memsys5"></a>
383
<h4>3.1.3 Zero-malloc memory allocator</h4>
385
<p>When SQLite is compiled with the <a href="compile.html#enable_memsys5">SQLITE_ENABLE_MEMSYS5</a> option, an
386
alternative memory allocator that does not use malloc() is included in the
387
build. The SQLite developers refer to this alternative memory allocator
388
as "memsys5". Even when it is included in the build, memsys5 is
390
To enable memsys5, the application must invoke the following SQLite
391
interface at start-time:</p>
394
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>, pBuf, szBuf, mnReq);
397
<p>In the call above, pBuf is a pointer to a large, contiguous chunk
398
of memory space that SQLite will use to satisfy all of its memory
399
allocation needs. pBuf might point to a static array or it might
400
be memory obtained from some other application-specific mechanism.
401
szBuf is an integer that is the number of bytes of memory space
402
pointed to by pBuf. mnReq is another integer that is the
403
minimum size of an allocation. Any call to <a href="c3ref/free.html">sqlite3_malloc(N)</a> where
404
N is less than mnReq will be rounded up to mnReq. mnReq must be
405
a power of two. We shall see later that the mnReq parameter is
406
important in reducing the value of <b>n</b> and hence the minimum memory
407
size requirement in the <a href="malloc.html#nofrag">Robson proof</a>.</p>
409
<p>The memsys5 allocator is designed for use on embedded systems,
410
though there is nothing to prevent its use on workstations.
411
The szBuf is typically between a few hundred kilobytes up to a few
412
dozen megabytes, depending on system requirements and memory budget.</p>
414
<p>The algorithm used by memsys5 can be called "power-of-two,
415
first-fit". The sizes of all memory allocation
416
requests are rounded up to a power of two and the request is satisfied
417
by the first free slot in pBuf that is large enough. Adjacent freed
418
allocations are coalesced using a buddy system. When used appropriately,
419
this algorithm provides mathematical guarantees against fragmentation and
420
breakdown, as described further <a href="#nofrag">below</a>.</p>
422
<a name="memsysx"></a>
424
<h4>3.1.4 Experimental memory allocators</h4>
426
<p>The name "memsys5" used for the zero-malloc memory allocator implies
427
that there are several additional memory allocators available, and indeed
428
there are. The default memory allocator is "memsys1". The debugging
429
memory allocator is "memsys2". Those have already been covered.</p>
431
<p>If SQLite is compiled with <a href="compile.html#enable_memsys3">SQLITE_ENABLE_MEMSYS3</a> than another
432
zero-malloc memory allocator, similar to memsys5, is included in the
433
source tree. The memsys3 allocator, like memsys5, must be activated
434
by a call to <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>,...). Memsys3
435
uses the memory buffer supplied as its source for all memory allocations.
436
The difference between memsys3 and memsys5 is that memsys3 uses a
437
different memory allocation algorithm that seems to work well in
438
practice, but which does not provide mathematical
439
guarantees against memory fragmentation and breakdown. Memsys3 was
440
a predecessor to memsys5. The SQLite developers now believe that
441
memsys5 is superior to
442
memsys3 and that all applications that need a zero-malloc memory
443
allocator should use memsys5 in preference to memsys3. Memsys3 is
444
considered both experimental and deprecated and will likely be removed
445
from the source tree in a future release of SQLite.</p>
447
<p>Code for memsys4 is still in the SQLite source tree (as of this writing -
448
SQLite <a href="releaselog/3_6_1.html">version 3.6.1</a>), but it has not been maintained for several release
449
cycles and probably does not work. (Update: memsys4 was removed as
450
of <a href="releaselog/3_6_5.html">version 3.6.5</a>) Memsys4 was an attempt to use mmap()
451
to obtain memory and then use madvise() to release unused pages
452
back to the operating system so that they could be reused by other
453
processes. The work on memsys4 has been abandoned and the memsys4 module
454
will likely be removed from the source tree in the near future.</p>
456
<p>Memsys6 uses system malloc() and free() to obtain the memory it needs.
457
Memsys6 serves as an aggregator. Memsys6 only calls system malloc() to obtain
458
large allocations. It then subdivides those large allocations to services
459
multiple smaller memory allocation requests coming from the SQLite core.
460
Memsys6 is intended for use in systems where
461
system malloc() is particularly inefficient. The idea behind memsys6 is
462
to reduce the number of calls to system malloc() by a factor of 10 or more.</p>
464
<p>Memsys6 is made available by compiling SQLite with the SQLITE_ENABLE_MEMSYS6
465
compile-time option and then at start-time invoking:</p>
468
<a href="c3ref/config.html">sqlite3_config</a>(SQLITE_CONFIG_CHUNKALLOC);
471
<p>Memsys6 was added in SQLite <a href="releaselog/3_6_1.html">version 3.6.1</a>.
472
It is very experimental. Its future is uncertain and it may be removed
473
in a subsequent release. Update: Memsys6 was removed as of
474
<a href="releaselog/3_6_5.html">version 3.6.5</a>.</p>
476
<p>Other experimental memory allocators might be added in future releases
477
of SQLite. One many anticipate that these will be called memsys7, memsys8,
480
<a name="appalloc"></a>
481
<h4>3.1.5 Application-defined memory allocators</h4>
483
<p>New memory allocators do not have to be part of the SQLite source tree
484
nor included in the sqlite3.c <a href="amalgamation.html">amalgamation</a>. Individual applications can
485
supply their own memory allocators to SQLite at start-time.</p>
487
<p>To cause SQLite to use a new memory allocator, the application
491
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>, pMem);
494
<p>In the call above, pMem is a pointer to an <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object
495
that defines the interface to the application-specific memory allocator.
496
The <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> object is really just a structure containing
497
pointers to functions to implement the various memory allocation primitives.
500
<p>In a multi-threaded application, access to the <a href="c3ref/mem_methods.html">sqlite3_mem_methods</a>
501
is serialized if and only if <a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is enabled.
502
If <a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is disabled then the methods in
503
<a href="c3ref/mem_methods.html">sqlite3_mem_methods</a> must take care of their own serialization needs.</p>
505
<a name="overlayalloc"></a>
506
<h4>3.1.6 Memory allocator overlays</h4>
508
<p>An application can insert layers or "overlays" in between the
509
SQLite core and the underlying memory allocator.
510
For example, the <a href="#oomtesting">out-of-memory test logic</a>
511
for SQLite uses an overlay that can simulate memory allocation
514
<p>An overlay can be created by using the</p>
517
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfiggetmalloc">SQLITE_CONFIG_GETMALLOC</a>, pOldMem);
520
<p>interface to obtain pointers to the existing memory allocator.
521
The existing allocator is saved by the overlay and is used as
522
a fallback to do real memory allocation. Then the overlay is
523
inserted in place of the existing memory allocator using
524
the <a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a>,...) as described
525
<a href="#appalloc">above</a>.
527
<a name="stuballoc"></a>
528
<h4>3.1.7 No-op memory allocator stub</h4>
530
<p>If SQLite is compiled with the <a href="compile.html#zero_malloc">SQLITE_ZERO_MALLOC</a> option, then
531
the <a href="malloc.html#defaultalloc">default memory allocator</a> is omitted and replaced by a stub
532
memory allocator that never allocates any memory. Any calls to the
533
stub memory allocator will report back that no memory is available.</p>
535
<p>The no-op memory allocator is not useful by itself. It exists only
536
as a placeholder so that SQLite has a memory allocator to link against
537
on systems that may not have malloc(), free(), or realloc() in their
539
An application that is compiled with <a href="compile.html#zero_malloc">SQLITE_ZERO_MALLOC</a> will need to
540
use <a href="c3ref/config.html">sqlite3_config()</a> together with <a href="c3ref/c_config_getmalloc.html#sqliteconfigmalloc">SQLITE_CONFIG_MALLOC</a> or
541
<a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a> to specify a new alternative memory allocator
542
before beginning to use SQLite.</p>
544
<a name="scratch"></a>
546
<h3>3.2 Scratch memory</h3>
548
<p>SQLite occasionally needs a large chunk of "scratch" memory to
549
perform some transient calculation. Scratch memory is used, for example,
550
as temporary storage when rebalancing a B-Tree. These scratch memory
551
allocations are typically about 10 kilobytes in size and are
553
only for the duration of a single, short-lived function call.</p>
555
<p>In older versions of SQLite, the scratch memory was obtained from
556
the processor stack. That works great on workstations with a large stack.
557
But pulling large buffers from the stack
558
caused problems on embedded systems with a
559
small processor stack (typically 4K or 8K). And so SQLite was modified
560
to allocate scratch memory from the heap.</p>
562
<p>However, doing occasional large transient allocations from the heap can
563
lead to memory fragmentation in embedded systems. To work around this
564
problem, a separate memory allocation system for scratch memory has been
567
<p>The scratch memory allocator is set up as follows:</p>
570
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigscratch">SQLITE_CONFIG_SCRATCH</a>, pBuf, sz, N);
573
<p>The pBuf parameter is a pointer to a contiguous range of bytes that
574
SQLite will use for all scratch memory allocations. The buffer must be
575
at least sz*N bytes in size. The "sz" parameter
576
is the maximum size of each scratch allocation. N is the maximum
577
number of simultaneous scratch allocations. The "sz" parameter should
578
be approximately 6 times the maximum database page size. N should
579
be twice the number of threads running in the system. No single thread will
580
ever request more than two scratch allocation at a time so if there
581
are never more than N threads, then there will always be enough scratch
582
memory available.</p>
584
<p>If the scratch memory setup does not define enough memory, then
585
SQLite falls back to using the regular memory allocator for its scratch
586
memory allocations. The default setup is sz=0 and N=0 so the use
587
of the regular memory allocator is the default behavior.</p>
589
<a name="pagecache"></a>
591
<h3>3.3 Page cache memory</h3>
593
<p>In most applications, the database page cache subsystem within
594
SQLite uses more dynamically allocated memory than all other parts
595
of SQLite combined. It is not unusual to see the database page cache
596
consumes over 10 times more memory than the rest of SQLite combined.</p>
598
<p>SQLite can be configured to make page cache memory allocations from
599
a separate and distinct memory pool of fixed-size
600
slots. This can have two advantages:</p>
604
Because allocations are all the same size, the memory allocator can
605
operate much faster. The allocator need not bother with coalescing
606
adjacent free slots or searching for a slot
607
of an appropriate size. All unallocated memory slots can be stored on
608
a linked list. Allocating consists of removing the first entry from the
609
list. Deallocating is simply adding an entry to the beginning of the list.
613
With a single allocation size, the <b>n</b> parameter in the
614
<a href="malloc.html#nofrag">Robson proof</a> is 1, and the total memory space required by the allocator
615
(<b>N</b>) is exactly equal to maximum memory used (<b>M</b>).
616
No additional memory is required to cover fragmentation overhead, thus
617
reducing memory requirements. This is particularly important for the
618
page cache memory since the page cache constitutes the largest component
619
of the memory needs of SQLite.
623
<p>The page-cache memory allocator is disabled by default.
624
An application can enabled it at start-time as follows:</p>
627
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigpagecache">SQLITE_CONFIG_PAGECACHE</a>, pBuf, sz, N);
630
<p>The pBuf parameter is a pointer to a contiguous range of bytes that
631
SQLite will use for page-cache memory allocations. The buffer must be
632
at least sz*N bytes in size. The "sz" parameter
633
is the size of each page-cache allocation. N is the maximum
634
number of available allocations.</p>
636
<p>If SQLite needs a page-cache entry that is larger than "sz" bytes or
637
if it needs more than N entries, it falls back to using the
638
general-purpose memory allocator.</p>
640
<a name="lookaside"></a>
642
<h3>3.4 Lookaside memory allocator</h3>
644
<p>SQLite <a href="c3ref/sqlite3.html">database connections</a> make many
645
small and short-lived memory allocations.
646
This occurs most commonly when compiling SQL statements using
647
<a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> but also to a lesser extent when running
648
<a href="c3ref/stmt.html">prepared statements</a> using <a href="c3ref/step.html">sqlite3_step()</a>. These small memory
649
allocations are used to hold things such as the names of tables
650
and columns, parse tree nodes, individual query results values,
651
and B-Tree cursor objects. There are consequently
652
many calls to malloc() and free() - so many calls that malloc() and
653
free() end up using a significant fraction of the CPU time assigned
656
<p>SQLite <a href="releaselog/3_6_1.html">version 3.6.1</a> introduced the lookaside memory allocator to
657
help reduce the memory allocation load. In the lookaside allocator,
658
each <a href="c3ref/sqlite3.html">database connection</a> preallocates a single large chunk of memory
659
(typically in the range of 50 to 100 kilobytes) and divides that chunk
660
up into small fixed-size "slots" of around 50 to 200 byte each. This
661
becomes the lookaside memory pool. Thereafter, memory allocations
662
associated with the <a href="c3ref/sqlite3.html">database connection</a> and that are not too larger
663
are satisfied using one of the lookaside pool slots rather than by calling
664
the general-purpose memory allocator. Larger allocations continue to
665
use the general-purpose memory allocator, as do allocations that occur
666
when the lookaside pool slots are all checked out.
667
But in many cases, the memory
668
allocations are small enough and there are few enough outstanding that
669
the new memory requests can be satisfied from the lookaside
672
<p>Because lookaside allocations are always the same size, the allocation
673
and deallocation algorithms are very quick. There is no
674
need to coalesce adjacent free slots or search for a slot
675
of a particular size. Each <a href="c3ref/sqlite3.html">database connection</a> maintains a singly-linked
676
list of unused slots. Allocation requests simply pull the first
677
element of this list. Deallocations simply push the element back onto
678
the front of the list.
679
Furthermore, each <a href="c3ref/sqlite3.html">database connection</a> is assumed to already be
680
running in a single thread (there are mutexes already in
681
place to enforce this) so no additional mutexing is required to
682
serialize access to the lookaside slot freelist.
683
Consequently, lookaside memory
684
allocations and deallocations are very fast. In speed tests on
685
Linux and Mac OS X workstations, SQLite has shown overall performance
686
improvements as high as 10% and 15%, depending on the workload how
687
lookaside is configured.</p>
689
<p>The size of the lookaside memory pool has a global default value
690
but can also be configured on a connection-by-connection basis.
691
To change the default size of the lookaside memory pool use the
692
following interface at start-time:</p>
695
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfiglookaside">SQLITE_CONFIG_LOOKASIDE</a>, sz, cnt);
698
<p>The "sz" parameter is the size in bytes of each lookaside slot.
699
The default is 100 bytes. The "cnt" parameter is
700
the total number of lookaside memory slots per database connection.
701
The default value is 500 slots. The total amount
702
of lookaside memory allocated to each <a href="c3ref/sqlite3.html">database connection</a> is
703
sz*cnt bytes. Hence the lookaside memory pool allocated per database
704
connection is 50 kilobytes by default.
705
(Note: these default values are for SQLite <a href="releaselog/3_6_1.html">version 3.6.1</a> and are subject
706
to changes in future releases.)
709
<p>The lookaside pool can be changed for an individual
710
<a href="c3ref/sqlite3.html">database connection</a> "db" using this call:</p>
713
<a href="c3ref/db_config.html">sqlite3_db_config</a>(db, <a href="c3ref/c_dbconfig_enable_fkey.html">SQLITE_DBCONFIG_LOOKASIDE</a>, pBuf, sz, cnt);
716
<p>The "pBuf" parameter is a pointer to memory space that will be
717
used for the lookaside memory pool. If pBuf is NULL, then SQLite
718
will obtain its own space for the memory pool using <a href="c3ref/free.html">sqlite3_malloc()</a>.
719
The "sz" and "cnt" parameters are the size of each lookaside slot
720
and the number of slots, respectively. If pBuf is not NULL, then it
721
must point to at least sz*cnt bytes of memory.</p>
723
<p>The lookaside configuration can only be changed while there are
724
no outstanding lookaside allocations for the database connection.
725
Hence, the configuration should be set immediately after creating the
726
database connection using <a href="c3ref/open.html">sqlite3_open()</a> (or equivalent) and before
727
evaluating any SQL statements on the connection.</p>
729
<a name="memstatus"></a>
731
<h3>3.5 Memory status</h3>
733
<p>By default, SQLite keeps statistics on its memory usage. These
734
statistics are useful in helping to determine how much memory an
735
application really needs. The statistics can also be used in
736
high-reliability system to determine
737
if the memory usage is coming close to or exceeding the limits
738
of the <a href="malloc.html#nofrag">Robson proof</a> and hence that the memory allocation subsystem is
739
liable to breakdown.</p>
741
<p>Most memory statistics are global, and therefore the tracking of
742
statistics must be serialized with a mutex. Statistics are turned
743
on by default, but an option exists to disable them. By disabling
745
SQLite avoids entering and leaving a mutex on each memory allocation
746
and deallocation. That savings can be noticeable on systems where
747
mutex operations are expensive. To disable memory statistics, the
748
following interface is used at start-time:</p>
751
<a href="c3ref/config.html">sqlite3_config</a>(<a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a>, onoff);
754
<p>The "onoff" parameter is true to enable the tracking of memory
755
statistics and false to disable statistics tracking.</p>
757
<p>Assuming statistics are enabled, the following routine can be used
761
<a href="c3ref/status.html">sqlite3_status</a>(<a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">verb</a>, ¤t, &highwater, resetflag);
764
<p>The "verb" argument determines what statistic is accessed.
765
There are <a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">various verbs</a> defined. The
766
list is expected to grow as the <a href="c3ref/status.html">sqlite3_status()</a> interface matures.
767
The current value the selected parameter is written into integer
768
"current" and the highest historical value
769
is written into integer "highwater". If resetflag is true, then
770
the high-water mark is reset down to the current value after the call
773
<p>A different interface is used to find statistics associated with a
774
single <a href="c3ref/sqlite3.html">database connection</a>:</p>
777
<a href="c3ref/db_status.html">sqlite3_db_status</a>(db, <a href="c3ref/c_dbstatus_options.html#sqlitedbstatuslookasideused">verb</a>, ¤t, &highwater, resetflag);
780
<p>This interface is similar except that it takes a pointer to
781
a <a href="c3ref/sqlite3.html">database connection</a> as its first argument and returns statistics about
782
that one object rather than about the entire SQLite library.
783
The <a href="c3ref/db_status.html">sqlite3_db_status()</a> interface currently only recognizes a
784
single verb <a href="c3ref/c_dbstatus_options.html#sqlitedbstatuslookasideused">SQLITE_DBSTATUS_LOOKASIDE_USED</a>, though additional verbs
785
may be added in the future.</p>
787
<p>The per-connection statistics do not use global variables and hence
788
do not require mutexes to update or access. Consequently the
789
per-connection statistics continue to function even if
790
<a href="c3ref/c_config_getmalloc.html#sqliteconfigmemstatus">SQLITE_CONFIG_MEMSTATUS</a> is turned off.</p>
792
<a name="heaplimit"></a>
793
<h3>3.6 Setting memory usage limits</h3>
795
<p>The <a href="c3ref/soft_heap_limit64.html">sqlite3_soft_heap_limit64()</a> interface can be used to set an
796
upper bound on the total amount of outstanding memory that the
797
general-purpose memory allocator for SQLite will allow to be outstanding
798
at one time. If attempts are made to allocate more memory that specified
799
by the soft heap limit, then SQLite will first attempt to free cache
800
memory before continuing with the allocation request. The soft heap
801
limit mechanism only works if <a href="malloc.html#memstatus">memory statistics</a> are enabled and
803
if the SQLite library is compiled with the <a href="compile.html#enable_memory_management">SQLITE_ENABLE_MEMORY_MANAGEMENT</a>
804
compile-time option.</p>
806
<p>The soft heap limit is "soft" in this sense: If SQLite is not able
807
to free up enough auxiliary memory to stay below the limit, it goes
808
ahead and allocations the extra memory and exceeds its limit. This occurs
809
under the theory that it is better to use additional memory than to fail
812
<p>As of SQLite version 3.6.1, the soft heap limit only applies to the
813
general-purpose memory allocator. The soft heap limit does not know
814
about or interact with the <a href="malloc.html#scratch">scratch memory allocator</a>,
815
the <a href="malloc.html#pagecache">pagecache memory allocator</a>, or the <a href="malloc.html#lookaside">lookaside memory allocator</a>.
816
This deficiency will likely be addressed in a future release.</p>
818
<a name="nofrag"></a>
820
<h2>4.0 Mathematical Guarantees Against Memory Allocation Failures</h2>
822
<p>The problem of dynamic memory allocation, and specifically the
823
problem of a memory allocator breakdown, has been studied by
824
J. M. Robson and the results published as:</p>
827
J. M. Robson. "Bounds for Some Functions Concerning Dynamic
828
Storage Allocation". <i>Journal of the Association for
829
Computing Machinery</i>, Volume 21, Number 8, July 1974,
833
<p>Let us use the following notation (similar but not identical to
834
Robson's notation):</p>
837
<table cellpadding="10" border="0">
838
<tr><td valign="top"><b>N</b></td>
840
The amount of raw memory needed by the memory allocation system
841
in order to guarantee that no memory allocation will ever fail.
843
<tr><td valign="top"><b>M</b></td>
845
The maximum amount of memory that the application ever has checked out
846
at any point in time.
848
<tr><td valign="top"><b>n</b></td>
850
The ratio of the largest memory allocation to the smallest. We assume
851
that every memory allocation size is an integer multiple of the smallest memory
857
<p>Robson proves the following result:</p>
860
<b>N</b> = <b>M</b>*(1 + (log<sub>2</sub> <b>n</b>)/2) - <b>n</b> + 1
863
<p>Colloquially, the Robson proof shows that in order to guarantee
864
breakdown-free operation, any memory allocator must use a memory pool
865
of size <b>N</b> which exceeds the maximum amount of memory ever
866
used <b>M</b> by a multiplier that depends on <b>n</b>,
867
the ratio of the largest to the smallest allocation size. In other
868
words, unless all memory allocations are of exactly the same size
869
(<b>n</b>=1) then the system needs access to more memory than it will
870
ever use at one time. Furthermore, we see that the amount of surplus
871
memory required grows rapidly as the ratio of largest to smallest
872
allocations increases, and so there is strong incentive to keep all
873
allocations as near to the same size as possible.</p>
875
<p>Robson's proof is constructive.
876
He provides an algorithm for computing a sequence of allocation
877
and deallocation operations that will lead to an allocation failure due to
878
memory fragmentation if available memory is as much as one byte
880
And, Robson shows that a power-of-two first-fit memory allocator
881
(such as implemented by <a href="malloc.html#memsys5">memsys5</a>) will never fail a memory allocation
882
provided that available memory is <b>N</b> or more bytes.</p>
884
<p>The values <b>M</b> and <b>n</b> are properties of the application.
885
If an application is constructed in such a way that both <b>M</b> and
886
<b>n</b> are known, or at least have known upper bounds, and if the
888
the <a href="malloc.html#memsys5">memsys5</a> memory allocator and is provided with <b>N</b> bytes of
889
available memory space using <a href="c3ref/c_config_getmalloc.html#sqliteconfigheap">SQLITE_CONFIG_HEAP</a>
890
then Robson proves that no memory allocation request will ever fail
891
within the application.
892
To put this another way, the application developer can select a value
893
for <b>N</b> that will guarantee that no call to any SQLite interface
894
will ever return <a href="c3ref/c_abort.html">SQLITE_NOMEM</a>. The memory pool will never become
895
so fragmented that a new memory allocation request cannot be satisfied.
896
This is an important property for
897
applications where a software fault could cause injury, physical harm, or
898
loss of irreplaceable data.</p>
900
<h3>4.1 Computing and controlling parameters <b>M</b> and <b>n</b></h3>
902
<p>The Robson proof applies separately to each of the memory allocators
906
<li>The general-purpose memory allocator (<a href="malloc.html#memsys5">memsys5</a>).</li>
907
<li>The <a href="malloc.html#scratch">scratch memory allocator</a>.</li>
908
<li>The <a href="malloc.html#pagecache">pagecache memory allocator</a>.</li>
909
<li>The <a href="malloc.html#lookaside">lookaside memory allocator</a>.</li>
912
<p>For allocators other than <a href="malloc.html#memsys5">memsys5</a>,
913
all memory allocations are of the same size. Hence, <b>n</b>=1
914
and therefore <b>N</b>=<b>M</b>. In other words, the memory pool need
915
be no larger than the largest amount of memory in use at any given moment.</p>
917
<p>SQLite guarantees that no thread will ever use more than two
918
scratch memory slots at one time. So if an application allocates twice as many
919
scratch memory slots as there are threads, and assuming the size of
920
each slot is large enough, there is never a chance of overflowing the
921
scratch memory allocator. An upper bound on the size of scratch memory
922
allocations is six times the largest page size. It is easy, therefore,
923
to guarantee breakdown-free operation of the scratch memory allocator.</p>
925
<p>The usage of pagecache memory is somewhat harder to control in
926
SQLite version 3.6.1, though mechanisms are planned for subsequent
927
releases that will make controlling pagecache memory much easier.
928
Prior to the introduction of these new mechanisms, the only way
929
to control pagecache memory is using the <a href="pragma.html#pragma_cache_size">cache_size pragma</a>.</p>
931
<p>Safety-critical applications will usually want to modify the
932
default lookaside memory configuration so that when the initial
933
lookaside memory buffer is allocated during <a href="c3ref/open.html">sqlite3_open()</a> the
934
resulting memory allocation is not so large as to force the <b>n</b>
935
parameter to be too large. In order to keep <b>n</b> under control,
936
it is best to try to keep the largest memory allocation below 2 or 4
937
kilobytes. Hence, a reasonable default setup for the lookaside
938
memory allocator might any one of the following:</p>
941
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 32, 32); /* 1K */
942
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 64, 32); /* 2K */
943
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 32, 64); /* 2K */
944
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 64, 64); /* 4K */
947
<p>Another approach is to initially disable the lookaside memory
951
sqlite3_config(SQLITE_CONFIG_LOOKASIDE, 0, 0);
954
<p>Then let the application maintain a separate pool of larger
955
lookaside memory buffers that it can distribute to <a href="c3ref/sqlite3.html">database connections</a>
956
as they are created. In the common case, the application will only
957
have a single <a href="c3ref/sqlite3.html">database connection</a> and so the lookaside memory pool
958
can consist of a single large buffer.</p>
961
sqlite3_db_config(db, SQLITE_DBCONFIG_LOOKASIDE, aStatic, 256, 500);
964
<p>The lookaside memory allocator is really intended as performance
965
optimization, not as a method for assuring breakdown-free memory allocation,
966
so it is not unreasonable to completely disable the lookaside memory
967
allocator for safety-critical operations.</p>
969
<p>The general purpose memory allocator is the most difficult memory pool
970
to manage because it supports allocations of varying sizes. Since
971
<b>n</b> is a multiplier on <b>M</b> we want to keep <b>n</b> as small
972
as possible. This argues for keeping the minimum allocation size for
973
<a href="malloc.html#memsys5">memsys5</a> as large as possible. In most applications, the
974
<a href="malloc.html#lookaside">lookaside memory allocator</a> is able to handle small allocations. So
975
it is reasonable to set the minimum allocation size for <a href="malloc.html#memsys5">memsys5</a> to
976
2, 4 or even 8 times the maximum size of a lookaside allocation.
977
A minimum allocation size of 512 is a reasonable setting.</p>
979
<p>Further to keeping <b>n</b> small, one desires to keep the size of
980
the largest memory allocations under control.
981
Large requests to the general-purpose memory allocator
982
might come from several sources:</p>
985
<li>SQL table rows that contain large strings or BLOBs.</li>
986
<li>Complex SQL queries that compile down to large <a href="c3ref/stmt.html">prepared statements</a>.</li>
987
<li>SQL parser objects used internally by <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a>.</li>
988
<li>Storage space for <a href="c3ref/sqlite3.html">database connection</a> objects.</li>
989
<li>Scratch memory allocations that overflow into the general-purpose
990
memory allocator.</li>
991
<li>Page cache memory allocations that overflow into the general-purpose
992
memory allocator.</li>
993
<li>Lookaside buffer allocations for new <a href="c3ref/sqlite3.html">database connections</a>.</li>
996
<p>The last three allocations can be controlled and/or eliminated by
997
configuring the <a href="malloc.html#scratch">scratch memory allocator</a>, <a href="malloc.html#pagecache">pagecache memory allocator</a>,
998
and <a href="malloc.html#lookaside">lookaside memory allocator</a> appropriately, as described above.
999
The storage space required for <a href="c3ref/sqlite3.html">database connection</a> objects depends
1000
to some extent on the length of the filename of the database file, but
1001
rarely exceeds 2KB on 32-bit systems. (More space is required on
1002
64-bit systems due to the increased size of pointers.)
1003
Each parser object uses about 1.6KB of memory. Thus, elements 3 through 7
1004
above can easily be controlled to keep the maximum memory allocation
1007
<p>If the application is designed to manage data in small pieces,
1008
then the database should never contain any large strings or BLOBs
1009
and hence element 1 above should not be a factor. If the database
1010
does contain large strings or BLOBs, they should be read using
1011
<a href="c3ref/blob.html">incremental BLOB I/O</a> and rows that contain the
1012
large strings or BLOBs should never be update by any means other
1013
than <a href="c3ref/blob.html">incremental BLOB I/O</a>. Otherwise, the
1014
<a href="c3ref/step.html">sqlite3_step()</a> routine will need to read the entire row into
1015
contiguous memory at some point, and that will involve at least
1016
one large memory allocation.</p>
1018
<p>The final source of large memory allocations is the space to hold
1019
the <a href="c3ref/stmt.html">prepared statements</a> that result from compiling complex SQL
1020
operations. Ongoing work by the SQLite developers is reducing the
1021
amount of space required here. But large and complex queries might
1022
still require <a href="c3ref/stmt.html">prepared statements</a> that are several kilobytes in
1023
size. The only workaround at the moment is for the application to
1024
break complex SQL operations up into two or more smaller and simpler
1025
operations contained in separate <a href="c3ref/stmt.html">prepared statements</a>.</p>
1027
<p>All things considered, applications should normally be able to
1028
hold their maximum memory allocation size below 2K or 4K. This
1029
gives a value for log<sub>2</sub>(<b>n</b>) of 2 or 3. This will
1030
limit <b>N</b> to between 2 and 2.5 times <b>M</b>.</p>
1032
<p>The maximum amount of general-purpose memory needed by the application
1033
is determined by such factors as how many simultaneous open
1034
<a href="c3ref/sqlite3.html">database connection</a> and <a href="c3ref/stmt.html">prepared statement</a> objects the application
1035
uses, and on the complexity of the <a href="c3ref/stmt.html">prepared statements</a>. For any
1036
given application, these factors are normally fixed and can be
1037
determined experimentally using <a href="c3ref/c_status_malloc_count.html#sqlitestatusmemoryused">SQLITE_STATUS_MEMORY_USED</a>.
1038
A typical application might only use about 40KB of general-purpose
1039
memory. This gives a value of <b>N</b> of around 100KB.</p>
1041
<h3>4.2 Ductile failure</h3>
1043
<p>If the memory allocation subsystems within SQLite are configured
1044
for breakdown-free operation but the actual memory usage exceeds
1045
design limits set by the <a href="malloc.html#nofrag">Robson proof</a>, SQLite will usually continue
1046
to operate normally.
1047
The <a href="malloc.html#scratch">scratch memory allocator</a>, the <a href="malloc.html#pagecache">pagecache memory allocator</a>,
1048
and the <a href="malloc.html#lookaside">lookaside memory allocator</a> all automatically failover
1049
to the <a href="malloc.html#memsys5">memsys5</a> general-purpose memory allocator. And it is usually the
1050
case that the <a href="malloc.html#memsys5">memsys5</a> memory allocator will continue to function
1051
without fragmentation even if <b>M</b> and/or <b>n</b> exceeds the limits
1052
imposed by the <a href="malloc.html#nofrag">Robson proof</a>. The <a href="malloc.html#nofrag">Robson proof</a> shows that it is
1053
possible for a memory allocation to break down and fail in this
1054
circumstance, but such a failure requires an especially
1055
despicable sequence of allocations and deallocations - a sequence that
1056
SQLite has never been observed to follow. So in practice it is usually
1057
the case that the limits imposed by Robson can be exceeded by a
1058
considerable margin with no ill effect.</p>
1060
<p>Nevertheless, application developers are admonished to monitor
1061
the state of the memory allocation subsystems and raise alarms when
1062
memory usage approaches or exceeds Robson limits. In this way,
1063
the application will provide operators with abundant warning well
1064
in advance of failure.
1065
The <a href="malloc.html#memstatus">memory statistics</a> interfaces of SQLite provide the application with
1066
all the mechanism necessary to complete the monitoring portion of
1069
<a name="stability"></a>
1070
<h2>5.0 Stability Of Memory Interfaces</h2>
1072
<p>As of this writing (circa SQLite version 3.6.1) all of the alternative
1073
memory allocators and mechanisms for manipulating, controlling, and
1074
measuring memory allocation in SQLite are considered experimental and
1075
subject to change from one release to the next. These interfaces are
1076
in the process of being refined to work on a wide variety of systems
1077
under a range of constraints. The SQLite developers need the flexibility
1078
to change the memory allocator interfaces in order to best meet the
1079
needs of a wide variety of systems.</p>
1081
<p>One may anticipate that the memory allocator interfaces will
1082
eventually stabilize. Appropriate notice will be given when that
1083
occurs. In the meantime, applications developers who make use of
1084
these interfaces need to be prepared to modify their applications
1085
to accommodate changes in the SQLite interface.</p>
1087
<p><b>Update:</b> As of SQLite version 3.7.0, all of these interfaces
1088
are considered stable</p>
1090
<a name="summary"></a>
1091
<h2>6.0 Summary Of Memory Allocator Interfaces</h2>
1093
<p><i>To be completed...</i></p>
added
removed
malloc.html
