Documentation Source Text

Check-in [161f14d929]
Login

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

Overview
Comment:Various documentation typo fixes and updates.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 161f14d929aa1266b669cf964a466ca6e36d3f34
User & Date: drh 2010-09-29 01:38:15.000
Context
2010-09-29
04:20
Fix documentation typos in testing.html and in fileformat2.html. (check-in: ac93c65159 user: drh tags: trunk)
01:38
Various documentation typo fixes and updates. (check-in: 161f14d929 user: drh tags: trunk)
2010-09-28
17:38
Changes to the CREATE TABLE documentation. (check-in: 2092d92251 user: dan tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/capi3ref.in.
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
<p>The content on these pages is extracted from comments
in the source code.</p>

<p>The interface is broken down into three categories:</p>

<ol>
<li><p><a href="objlist.html"><b>List Of Objects.</b></a>
    All abstract objects and datatypes used by the
    SQLite library.  There are a handful of objects, but
    only three which most users need to be aware of:
    A database connection object [sqlite3], 
    prepared statement object [sqlite3_stmt], and the 64-bit integer
    type [sqlite3_int64].</p></li>

<li><p><a href="constlist.html"><b>List Of Constants.</b></a>
    Numeric constants just by SQLite and represented by
    #defines in the sqlite3.h header file.  These constants
    are things such as numeric return parameters from
    various interfaces (ex: [SQLITE_OK] or flags passed
    into functions to control behavior
    (ex: [SQLITE_OPEN_READONLY]).</p></li>

<li><p><a href="funclist.html"><b>List Of Functions.</b></a>
    Functions and/or methods operating on the 
    <a href="objlist.html">objects</a> and using and/or
    returning <a href="constlist.html">constants</a>.  There
    are many functions, but most applications only use a handful.
    </p></li>
</ol>

<tcl>







|
|
|





|







|







244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
<p>The content on these pages is extracted from comments
in the source code.</p>

<p>The interface is broken down into three categories:</p>

<ol>
<li><p><a href="objlist.html"><b>List Of Objects.</b></a>
    This is a list of all abstract objects and datatypes used by the
    SQLite library.  There are couple dozen objects in total, but
    the three most important objects are:
    A database connection object [sqlite3], 
    prepared statement object [sqlite3_stmt], and the 64-bit integer
    type [sqlite3_int64].</p></li>

<li><p><a href="constlist.html"><b>List Of Constants.</b></a>
    This is a list of numeric constants used by SQLite and represented by
    #defines in the sqlite3.h header file.  These constants
    are things such as numeric return parameters from
    various interfaces (ex: [SQLITE_OK] or flags passed
    into functions to control behavior
    (ex: [SQLITE_OPEN_READONLY]).</p></li>

<li><p><a href="funclist.html"><b>List Of Functions.</b></a>
    This is a list of all functions and methods operating on the 
    <a href="objlist.html">objects</a> and using and/or
    returning <a href="constlist.html">constants</a>.  There
    are many functions, but most applications only use a handful.
    </p></li>
</ol>

<tcl>
Changes to pages/cintro.in.
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<p>
  This article provides an overview and roadmap to the C/C++ interface
  to SQLite.
</p>

<p>
  Early versions of SQLite were very easy to learn since they only
  supported 5 C/C++ interfaces.  But as SQLite has grown in capability
  new C/C++ interfaces have been added so that now there
  are over 150 distinct APIs.  This can be overwhelming to a new programmer.
  Fortunately, most of the C/C++ interfaces in SQLite are very specialized
  and never need to be used.  Despite having so many
  entry points, the core API is still relatively simple and easy to code to.
  This article aims to provide all of the background information needed to
  easily understand how SQLite works.
</p>








|

|







41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
<p>
  This article provides an overview and roadmap to the C/C++ interface
  to SQLite.
</p>

<p>
  Early versions of SQLite were very easy to learn since they only
  supported 5 C/C++ interfaces.  But as SQLite has grown in capability,
  new C/C++ interfaces have been added so that now there
  are over 185 distinct APIs.  This can be overwhelming to a new programmer.
  Fortunately, most of the C/C++ interfaces in SQLite are very specialized
  and never need to be used.  Despite having so many
  entry points, the core API is still relatively simple and easy to code to.
  This article aims to provide all of the background information needed to
  easily understand how SQLite works.
</p>

291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
  <li> [sqlite3_bind_int | sqlite3_bind()] </li>
</ul></p>

<p>
  After a [prepared statement] has been evaluated by one or more calls to
  [sqlite3_step()], it can be reset in order to be evaluated again by a
  call to [sqlite3_reset()].
  Using [sqlite3_reset()] on an existing [prepared statement] rather
  creating a new [prepared statement] avoids unnecessary calls to
  [sqlite3_prepare()].
  In many SQL statements, the time needed
  to run [sqlite3_prepare()] equals or exceeds the time needed by
  [sqlite3_step()].  So avoiding calls to [sqlite3_prepare()] can result
  in a significant performance improvement.
</p>







|







291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
  <li> [sqlite3_bind_int | sqlite3_bind()] </li>
</ul></p>

<p>
  After a [prepared statement] has been evaluated by one or more calls to
  [sqlite3_step()], it can be reset in order to be evaluated again by a
  call to [sqlite3_reset()].
  Using [sqlite3_reset()] on an existing [prepared statement] rather than
  creating a new [prepared statement] avoids unnecessary calls to
  [sqlite3_prepare()].
  In many SQL statements, the time needed
  to run [sqlite3_prepare()] equals or exceeds the time needed by
  [sqlite3_step()].  So avoiding calls to [sqlite3_prepare()] can result
  in a significant performance improvement.
</p>
Changes to pages/index.in.
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_7_2.html">Version 3.7.2</a>
of SQLite is recommended for all new development.
Upgrading from all prior SQLite versions is recommended.</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>







|







83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

</td>
<td width="20"></td><td bgcolor="#044a64" width="1"></td><td width="20"></td>
<td valign="top">
<h3>Current Status</h3>

<p><ul>
<li><a href="releaselog/3_7_3.html">Version 3.7.3</a>
of SQLite is recommended for all new development.
Upgrading from all prior SQLite versions is recommended.</li>
</ul></p>

<h3>Common Links</h3>

<p><ul>
Changes to pages/lang.in.
3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
normally quote any identifier that is an English language word, even if
you do not have to.
</p>

<p>
The list below shows all possible keywords used by any build of
SQLite regardless of [compile-time options].  
Most reasonable configurations use more or all of these keywords,
but some keywords may be omitted when SQL language features are
disabled.
^(Regardless of the compile-time configuration, any identifier that is not on
the following <tcl>hd_puts [llength $keyword_list]</tcl> element
list is not a keyword to the SQL parser in SQLite:
</p>








|







3545
3546
3547
3548
3549
3550
3551
3552
3553
3554
3555
3556
3557
3558
3559
normally quote any identifier that is an English language word, even if
you do not have to.
</p>

<p>
The list below shows all possible keywords used by any build of
SQLite regardless of [compile-time options].  
Most reasonable configurations use most or all of these keywords,
but some keywords may be omitted when SQL language features are
disabled.
^(Regardless of the compile-time configuration, any identifier that is not on
the following <tcl>hd_puts [llength $keyword_list]</tcl> element
list is not a keyword to the SQL parser in SQLite:
</p>

Changes to pages/malloc.in.
1
2
3
4
5
6
7
8
9
10
11
12
13
<title>Dynamic Memory Allocation In SQLite</title>

<h1>Dynamic Memory Allocation In SQLite</h1>
<tcl>hd_keywords {memory allocation}</tcl>

<p>SQLite uses of dynamic memory allocation to obtain
memory for storing various objects
(ex: [database connections] and [prepared statements]) and to build
a memory cache of the database file and to hold the results of queries.
Much effort has gone into making the dynamic memory allocation subsystem
of SQLite reliable, predictable, robust, and efficient.</p>

<p>This document provides an overview of dynamic memory allocation within 





|







1
2
3
4
5
6
7
8
9
10
11
12
13
<title>Dynamic Memory Allocation In SQLite</title>

<h1>Dynamic Memory Allocation In SQLite</h1>
<tcl>hd_keywords {memory allocation}</tcl>

<p>SQLite uses dynamic memory allocation to obtain
memory for storing various objects
(ex: [database connections] and [prepared statements]) and to build
a memory cache of the database file and to hold the results of queries.
Much effort has gone into making the dynamic memory allocation subsystem
of SQLite reliable, predictable, robust, and efficient.</p>

<p>This document provides an overview of dynamic memory allocation within 
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462

<p>The pBuf parameter is a pointer to a contiguous range of bytes that
SQLite will use for all scratch memory allocations.  The buffer must be
at least sz*N bytes in size.  The "sz" parameter
is the maximum size of each scratch allocation.  N is the maximum 
number of simultaneous scratch allocations.  The "sz" parameter should
be approximately 6 times the maximum database page size.  N should
be the number of threads running in the system.  No single thread will
ever request more than one scratch allocation at a time so if there
are never more than N threads, then there will always be enough scratch
memory available.</p>

<p>If the scratch memory setup does not define enough memory, then
SQLite falls back to using the regular memory allocator for its scratch
memory allocations.  The default setup is sz=0 and N=0 so the use
of the regular memory allocator is the default behavior.</p>







|
|







447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462

<p>The pBuf parameter is a pointer to a contiguous range of bytes that
SQLite will use for all scratch memory allocations.  The buffer must be
at least sz*N bytes in size.  The "sz" parameter
is the maximum size of each scratch allocation.  N is the maximum 
number of simultaneous scratch allocations.  The "sz" parameter should
be approximately 6 times the maximum database page size.  N should
be twice the number of threads running in the system.  No single thread will
ever request more than two scratch allocation at a time so if there
are never more than N threads, then there will always be enough scratch
memory available.</p>

<p>If the scratch memory setup does not define enough memory, then
SQLite falls back to using the regular memory allocator for its scratch
memory allocations.  The default setup is sz=0 and N=0 so the use
of the regular memory allocator is the default behavior.</p>
660
661
662
663
664
665
666
667
668
669
670
671
672
673

674
675
676
677
678
679
680
do not require mutexes to update or access.  Consequently the
per-connection statistics continue to function even if
[SQLITE_CONFIG_MEMSTATUS] is turned off.</p>

<a name="heaplimit"></a>
<h3>3.6 Setting memory usage limits</h3>

<p>The [sqlite3_soft_heap_limit()] interface can be used to set an
upper bound on the total amount of outstanding memory that the
general-purpose memory allocator for SQLite will allow to be outstanding
at one time.  If attempts are made to allocate more memory that specified
by the soft heap limit, then SQLite will first attempt to free cache
memory before continuing with the allocation request.  The soft heap
limit mechanism only works if [memory statistics] are enabled and

if the SQLite library is compiled with the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
compile-time option.</p>

<p>The soft heap limit is "soft" in this sense:  If SQLite is not able
to free up enough auxiliary memory to stay below the limit, it goes
ahead and allocations the extra memory and exceeds its limit.  This occurs
under the theory that it is better to use additional memory than to fail







|






>







660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
do not require mutexes to update or access.  Consequently the
per-connection statistics continue to function even if
[SQLITE_CONFIG_MEMSTATUS] is turned off.</p>

<a name="heaplimit"></a>
<h3>3.6 Setting memory usage limits</h3>

<p>The [sqlite3_soft_heap_limit64()] interface can be used to set an
upper bound on the total amount of outstanding memory that the
general-purpose memory allocator for SQLite will allow to be outstanding
at one time.  If attempts are made to allocate more memory that specified
by the soft heap limit, then SQLite will first attempt to free cache
memory before continuing with the allocation request.  The soft heap
limit mechanism only works if [memory statistics] are enabled and
it works best
if the SQLite library is compiled with the [SQLITE_ENABLE_MEMORY_MANAGEMENT]
compile-time option.</p>

<p>The soft heap limit is "soft" in this sense:  If SQLite is not able
to free up enough auxiliary memory to stay below the limit, it goes
ahead and allocations the extra memory and exceeds its limit.  This occurs
under the theory that it is better to use additional memory than to fail
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
</ul>

<p>For allocators other than [memsys5],
all memory allocations are of the same size.  Hence, <b>n</b>=1
and therefore <b>N</b>=<b>M</b>.  In other words, the memory pool need
be no larger than the largest amount of memory in use at any given moment.</p>

<p>SQLite guarantees that no thread will ever use more than a single
scratch memory slot at one time.  So if an application allocates as many
scratch memory slots as there are threads, and assuming the size of
each slot is large enough, there is never a chance of overflowing the
scratch memory allocator.  An upper bound on the size of scratch memory
allocations is six times the largest page size.  It is easy, therefore,
to guarantee breakdown-free operation of the scratch memory allocator.</p>

<p>The usage of pagecache memory is somewhat harder to control in







|
|







781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
</ul>

<p>For allocators other than [memsys5],
all memory allocations are of the same size.  Hence, <b>n</b>=1
and therefore <b>N</b>=<b>M</b>.  In other words, the memory pool need
be no larger than the largest amount of memory in use at any given moment.</p>

<p>SQLite guarantees that no thread will ever use more than two
scratch memory slots at one time.  So if an application allocates twice as many
scratch memory slots as there are threads, and assuming the size of
each slot is large enough, there is never a chance of overflowing the
scratch memory allocator.  An upper bound on the size of scratch memory
allocations is six times the largest page size.  It is easy, therefore,
to guarantee breakdown-free operation of the scratch memory allocator.</p>

<p>The usage of pagecache memory is somewhat harder to control in
949
950
951
952
953
954
955



956
957
958
959
960
needs of a wide variety of systems.</p>

<p>One may anticipate that the memory allocator interfaces will
eventually stabilize.  Appropriate notice will be given when that
occurs.  In the meantime, applications developers who make use of
these interfaces need to be prepared to modify their applications
to accommodate changes in the SQLite interface.</p>




<a name="summary"></a>
<h2>6.0 Summary Of Memory Allocator Interfaces</h2>

<p><i>To be completed...</i></p>







>
>
>





950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
needs of a wide variety of systems.</p>

<p>One may anticipate that the memory allocator interfaces will
eventually stabilize.  Appropriate notice will be given when that
occurs.  In the meantime, applications developers who make use of
these interfaces need to be prepared to modify their applications
to accommodate changes in the SQLite interface.</p>

<p><b>Update:</b> As of SQLite version 3.7.0, all of these interfaces
are considered stable</p>

<a name="summary"></a>
<h2>6.0 Summary Of Memory Allocator Interfaces</h2>

<p><i>To be completed...</i></p>