Documentation Source Text

Check-in [afc454f404]
Login

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

Overview
Comment:Enhanced markings for experimental and deprecated interfaces.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: afc454f404eaa4da44902b092c92a14d7e56ccd7
User & Date: drh 2008-08-04 13:45:13
Context
2008-08-04
18:08
Continuing work on the memory allocator documentation. check-in: 080d9901f8 user: drh tags: trunk
13:45
Enhanced markings for experimental and deprecated interfaces. check-in: afc454f404 user: drh tags: trunk
2008-07-31
17:13
Begin adding the document on memory allocation. Update the index and changes documents for the release of version 3.6.1. check-in: 8f269144c3 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/capi3ref.in.

12
13
14
15
16
17
18


19

20
21
22
23
24
25
26
..
79
80
81
82
83
84
85




86
87
88
89
90
91
92
...
148
149
150
151
152
153
154









155
156
157
158
159
160
161
...
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
...
228
229
230
231
232
233
234
235







236

237
238
239
240
241
242
243
...
324
325
326
327
328
329
330





















































331
332
333
334
335
336
337
338
339

340
341
342
343
344
345
346
347
348
349
350

351




352
353
354
355
356
357
358
...
362
363
364
365
366
367
368

369
370
371
372
373
374
375
376
377
378
379

380




381
382
383
384
385
386
387
...
393
394
395
396
397
398
399

400
401
402
403
404
405
406
407
408
409
410
411

412




413
414
415
416
417
418
419
...
434
435
436
437
438
439
440




441
442
443
444
445
446
447
448
449
450
451
452
set content {}     ;# List of records, one record per definition
set dcnt 0         ;# Number of individual declarations
set lineno 0       ;# input file line number
set intab 0        ;# In a covenents or limitations table
set inrow 0        ;# In a row of a table
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 


unset -nocomplain keyword


# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {
    set rowbody [string trim $rowbody]
................................................................................
      set lx [string trim [string range $line 3 end]]
      if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
        set type $cx
      } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
        foreach k $kx {
          set keyword($k) 1
        }




      } elseif {[regexp {^INVARIANTS:$} $lx]} {
        append body "\n<h3>Invariants:</h3>\n"
        starttab
        set phase 2
      } elseif {[regexp {^ASSUMPTIONS:$} $lx]} {
        append body "\n<h3>Assumptions:</h3>\n"
        starttab
................................................................................
          append reqdf <$df>
          regsub { *<[AHLS]\d\d\d\d\d>} $title {} title
        }
        set keyword($reqtag) 1
      }
      set kwlist [lsort [array names keyword]]
      unset -nocomplain keyword









      set key $type:$kwlist
      regsub -all { *\{[\w.]+\}} $body {} body
      set body [string map \
          {<todo> {<font color="red">(TODO: } </todo> )</font>} $body]
      set code [string map {& &amp; < &lt; > &gt;} $code]
      lappend content [list $key $title $type $kwlist $body $code]
      if {$reqtag!=""} {
................................................................................
        incr dcnt
      }
      append code $line\n
    }
  }
}


# Convert a tag name into the filename used for the
# multi-file version.
#
# Constants begin with SQLITE_.  The names are converted
# to lower case and prefixed with "c_".  If we did not
# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
# would collide.
................................................................................
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
      set entry [lindex $lx $j]
      if {$entry!=""} {
        foreach {link label} $entry break







        hd_resolve "<li>\[$link|$label\]</li>"

      }
    }
    hd_puts {</ul></td>}
  }
  hd_puts {</tr></table>}
}

................................................................................
proc preferred_keyword {keyword_list} {
  foreach kw $keyword_list {
    if {[regexp -nocase {^sqlite} $kw]} break
  }
  return $kw
}























































# Do a table of contents for objects
#
set objlist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="datatype"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]

  foreach kw $keywords {
    if {[regexp {^sqlite} $kw]} {
      lappend objlist [list $k $kw]
    }
  }
}
hd_open_aux c3ref/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1

hd_puts {<h2>Objects:</h2>}




output_list 3 [lsort $objlist]
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a>.}
hd_close_aux
hd_enable_main 1
................................................................................
#
set clist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="constant"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]

  foreach kw $keywords {
    if {[regexp {^SQLITE_} $kw]} {
      lappend clist [list $k $kw]
    }
  }
}
hd_open_aux c3ref/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1

hd_puts {<h2>Constants:</h2>}




set clist [lsort -index 1 $clist]
output_list 2 $clist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a>.</p>}
hd_enable_main 1
................................................................................
#
set funclist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="function"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]

  foreach kw $keywords {
    if {[regexp {^sqlite} $kw]} {
      lappend funclist [list $k $kw]
    }
  }
}
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords {capi3ref_funclist}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1

hd_puts {<h2>Functions:</h2>}




set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
................................................................................
  hd_enable_main 1
  eval hd_keywords $keywords

  hd_puts "<h2>$title</h2>"
  hd_puts "<blockquote><pre>"
  hd_puts "$code"
  hd_puts "</pre></blockquote>"




  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  hd_resolve <p>$body</p>
  hd_enable_main 0
  hd_puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  hd_enable_main 1
  hd_close_aux
  hd_puts "<hr>"
}
</tcl>







>
>

>







 







>
>
>
>







 







>
>
>
>
>
>
>
>
>







 







<







 







|
>
>
>
>
>
>
>
|
>







 







>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>









>


|








>
|
>
>
>
>







 







>


|








>
|
>
>
>
>







 







>


|









>
|
>
>
>
>







 







>
>
>
>












12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
..
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
...
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
...
215
216
217
218
219
220
221

222
223
224
225
226
227
228
...
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
...
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
...
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
...
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
...
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
set content {}     ;# List of records, one record per definition
set dcnt 0         ;# Number of individual declarations
set lineno 0       ;# input file line number
set intab 0        ;# In a covenents or limitations table
set inrow 0        ;# In a row of a table
set rowbody {}     ;# Content of a row
set rowtag {}      ;# 
set exflag 0       ;# True for experimental interfaces 
set obsflag 0      ;# True for obsolete interfaces
unset -nocomplain keyword
unset -nocomplain supported   ;# 0: stable.  1: experimental  2: deprecated

# End a table row or the complete table.
#
proc endrow {} {
  global inrow body rowbody rowtag keyword dflt_parent
  if {$inrow} {
    set rowbody [string trim $rowbody]
................................................................................
      set lx [string trim [string range $line 3 end]]
      if {[regexp {^CATEGORY: +([a-z]*)} $lx all cx]} {
        set type $cx
      } elseif {[regexp {^KEYWORDS: +(.*)} $lx all kx]} {
        foreach k $kx {
          set keyword($k) 1
        }
      } elseif {[regexp {^EXPERIMENTAL} $lx]} {
        set exflag 1
      } elseif {[regexp {^DEPRECATED} $lx]} {
        set obsflag 1
      } elseif {[regexp {^INVARIANTS:$} $lx]} {
        append body "\n<h3>Invariants:</h3>\n"
        starttab
        set phase 2
      } elseif {[regexp {^ASSUMPTIONS:$} $lx]} {
        append body "\n<h3>Assumptions:</h3>\n"
        starttab
................................................................................
          append reqdf <$df>
          regsub { *<[AHLS]\d\d\d\d\d>} $title {} title
        }
        set keyword($reqtag) 1
      }
      set kwlist [lsort [array names keyword]]
      unset -nocomplain keyword
      if {$exflag} {
        foreach kw $kwlist {set supported($kw) 1}
      } elseif {$obsflag} {
        foreach kw $kwlist {set supported($kw) 2}
      } else {
        foreach kw $kwlist {set supported($kw) 0}
      }
      set exflag 0
      set obsflag 0
      set key $type:$kwlist
      regsub -all { *\{[\w.]+\}} $body {} body
      set body [string map \
          {<todo> {<font color="red">(TODO: } </todo> )</font>} $body]
      set code [string map {& &amp; < &lt; > &gt;} $code]
      lappend content [list $key $title $type $kwlist $body $code]
      if {$reqtag!=""} {
................................................................................
        incr dcnt
      }
      append code $line\n
    }
  }
}


# Convert a tag name into the filename used for the
# multi-file version.
#
# Constants begin with SQLITE_.  The names are converted
# to lower case and prefixed with "c_".  If we did not
# do this, then the names "SQLITE_BLOB" and "sqlite3_blob"
# would collide.
................................................................................
  for {set i 0} {$i<$N} {incr i} {
    set start [expr {$i*$n}]
    set end [expr {($i+1)*$n}]
    hd_puts {<td valign="top"><ul>}
    for {set j $start} {$j<$end} {incr j} {
      set entry [lindex $lx $j]
      if {$entry!=""} {
        foreach {link label s} $entry break
        if {$s==1} {
          hd_resolve "<li>\[$link|$label\]&nbsp;&nbsp;"
          hd_resolve "\[experimental | <small><i>(exp)</i></small>\]</li>"
        } elseif {$s==2} {
          hd_resolve "<li>\[$link|$label\]&nbsp;&nbsp;"
          hd_resolve "\[deprecated | <small><i>(obs)</i></small>\]</li>"
        } else {
          hd_resolve "<li>\[$link|$label\]</li>"
        }
      }
    }
    hd_puts {</ul></td>}
  }
  hd_puts {</tr></table>}
}

................................................................................
proc preferred_keyword {keyword_list} {
  foreach kw $keyword_list {
    if {[regexp -nocase {^sqlite} $kw]} break
  }
  return $kw
}

# Do a page explaining what "experimental" means.
hd_open_aux c3ref/experimental.html
hd_header {Experimental Interfaces}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
hd_keywords experimental deprecated
</tcl>

<h2>Experimental And Deprecated Interfaces</h2>

<p>SQLite interfaces can be subdivided into three categories:</p>

<ol>
<li>Stable</li>
<li>Experimental</li>
<li>Deprecated</li>
</ol>

<p>Stable interfaces will be maintained indefinitely in a backwards
compatible way.  An application that uses only stable interfaces
should always be able to relink against a newer version of SQLite
without any changes.</p>

<p>Experiemental interfaces are subject to change.  
Applications that use experiemental interfaces
may need to be modified when upgrading to a newer SQLite release.
When new interfaces are added to SQLite, they generally begin
as experimental interfaces.  After an interface has been in use for
a while and the developers are confident that the design of the interface
is sound and worthy of long-term support, the interface is marked
as stable.</p>

<p>Deprecated interfaces have been superceded by better methods of
accomplishing the same thing and should be avoided in new applications.
Deprecated interfaces continue to be supported for the sake of
backwards compatibility.  At some point in the future, it is possible
that deprecated interfaces may be removed.</p>

<p>Key points:</p>

<ul>
<li>Experimental interfaces are subject to change and/or removal 
at any time.</li>

<li>Deprecated interfaces should not be used in new code and might
be removed in some future release.</li>
</ul>

<tcl>
hd_close_aux
hd_puts {<hr>}


# Do a table of contents for objects
#
set objlist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="datatype"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]
  set s $supported($k)
  foreach kw $keywords {
    if {[regexp {^sqlite} $kw]} {
      lappend objlist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/objlist.html
hd_header {List Of SQLite Objects}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Objects:</h2>
<p>Note: Objects marked with "[experimental | <small><i>exp</i></small>]"
are [experimental] and objects marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated].</p>
<tcl>
output_list 3 [lsort $objlist]
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="funclist.html">Functions</a>.}
hd_close_aux
hd_enable_main 1
................................................................................
#
set clist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="constant"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]
  set s $supported($k)
  foreach kw $keywords {
    if {[regexp {^SQLITE_} $kw]} {
      lappend clist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/constlist.html
hd_header {List Of SQLite Constants}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Constants:</h2>
<p>Note: Constants marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and constants marked with
"[deprecated | <small><i>(obs)</i></small>]" are [deprecated]</p>
<tcl>
set clist [lsort -index 1 $clist]
output_list 2 $clist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="objlist.html">Objects</a> and
<a href="funclist.html">Functions</a>.</p>}
hd_enable_main 1
................................................................................
#
set funclist {}
foreach c $content {
  foreach {key title type keywords body code} $c break
  if {$type!="function"} continue
  set keywords [lsort $keywords]
  set k [preferred_keyword $keywords]
  set s $supported($k)
  foreach kw $keywords {
    if {[regexp {^sqlite} $kw]} {
      lappend funclist [list $k $kw $s]
    }
  }
}
hd_open_aux c3ref/funclist.html
hd_header {List Of SQLite Functions}
hd_keywords {capi3ref_funclist}
hd_enable_main 0
hd_puts {<a href="intro.html"><h2>SQLite C Interface</h2></a>}
hd_enable_main 1
</tcl>
<h2>Functions:</h2>
<p>Note: Functions marked with "[experimental | <small><i>(exp)</i></small>]"
are [experimental] and functions marked with
[deprecated | <small><i>(obs)</i></small>] are [deprecated].</p>
<tcl>
set funclist [lsort -index 1 $funclist]
output_list 3 $funclist
hd_enable_main 0
hd_puts {<p>Other lists:
<a href="constlist.html">Constants</a> and
<a href="objlist.html">Objects</a>.</p>}
hd_enable_main 1
................................................................................
  hd_enable_main 1
  eval hd_keywords $keywords

  hd_puts "<h2>$title</h2>"
  hd_puts "<blockquote><pre>"
  hd_puts "$code"
  hd_puts "</pre></blockquote>"
  if {$supported($kw)==1} {
    hd_resolve {<p><b>Important:</b> This interface is [experimental]}
    hd_resolve {and is subject to change without notice.</p>}
  }
  regsub -all "\n\n+" $body "</p>\n\n<p>" body
  hd_resolve <p>$body</p>
  hd_enable_main 0
  hd_puts {<p>See also lists of
  <a href="objlist.html">Objects</a>,
  <a href="constlist.html">Constants</a>, and
  <a href="funclist.html">Functions</a>.</p>}
  hd_enable_main 1
  hd_close_aux
  hd_puts "<hr>"
}
</tcl>

Changes to pages/cintro.in.

41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
..
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
...
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
  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
  over the years, new C/C++ interfaces have been added so that now there
  are over 150 distinct APIs.  This can be overwhelming to a programmer
  new to SQLite.
  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>

................................................................................
  complete or authoritative reference for the SQLite API.
</p>

<tcl>HEADING 1 {Core Objects And Interfaces}</tcl>

<p>
  The principal function of an SQL database engine is to evaluate statements
  of SQL.  In order to accomplish this in SQLite, the developer needs
  to know about two objects:
</p>

<p><ul>
  <li> The [database connection] object: sqlite3 </li>
  <li> The [prepared statement] object: sqlite3_stmt </li>
</ul></p>
................................................................................
</p>

<table border="0" cellspacing="15">

<tr><td valign="top" align="right">[sqlite3_open()]</td>
<td valign="top">
  This routine 
  opens a connection to an SQLite database file and return a
  [database connection] object.  This is often the first SQLite API
  call that an application makes and is a prerequisite for most other
  SQLite APIs.  Many SQLite interfaces require a pointer to
  the [database connection] object as their first parameter and can
  be thought of as methods on the [database connection] object.
  This routine is the constructor for the [database connection] object.
</td>







|
|
<







 







|







 







|







41
42
43
44
45
46
47
48
49

50
51
52
53
54
55
56
..
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
...
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
  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>

................................................................................
  complete or authoritative reference for the SQLite API.
</p>

<tcl>HEADING 1 {Core Objects And Interfaces}</tcl>

<p>
  The principal function of an SQL database engine is to evaluate statements
  of SQL.  In order to accomplish this purpose, the developer needs
  to know about two objects:
</p>

<p><ul>
  <li> The [database connection] object: sqlite3 </li>
  <li> The [prepared statement] object: sqlite3_stmt </li>
</ul></p>
................................................................................
</p>

<table border="0" cellspacing="15">

<tr><td valign="top" align="right">[sqlite3_open()]</td>
<td valign="top">
  This routine 
  opens a connection to an SQLite database file and returns a
  [database connection] object.  This is often the first SQLite API
  call that an application makes and is a prerequisite for most other
  SQLite APIs.  Many SQLite interfaces require a pointer to
  the [database connection] object as their first parameter and can
  be thought of as methods on the [database connection] object.
  This routine is the constructor for the [database connection] object.
</td>

Changes to pages/malloc.in.

434
435
436
437
438
439
440
441
442
443
444


445
446
447
448
449
450
451
452
453
454
455
456

<a name="pagecache"></a>
<h3>3.3 Page cache memory</h3>

<p>The database page cache subsystem within SQLite uses more
dynamically allocated memory than any other part of SQLite.  In fact,
the database page cache usually consumes about 10 times more memory
than all other parts of SQLite combined.  

<a name="lookaside"></a>
<h3>3.4 Lookaside memory allocator</h3>



<a name="memstatus"></a>
<h3>3.5 Memory status</h3>

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

<a name="nofrag"></a>
<h2>4.0 Anti-fragmentation Guarantee</h2>

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







|



>
>












434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458

<a name="pagecache"></a>
<h3>3.3 Page cache memory</h3>

<p>The database page cache subsystem within SQLite uses more
dynamically allocated memory than any other part of SQLite.  In fact,
the database page cache usually consumes about 10 times more memory
than all other parts of SQLite combined.  ....</p>

<a name="lookaside"></a>
<h3>3.4 Lookaside memory allocator</h3>

<p>

<a name="memstatus"></a>
<h3>3.5 Memory status</h3>

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

<a name="nofrag"></a>
<h2>4.0 Anti-fragmentation Guarantee</h2>

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