Documentation Source Text

Check-in [668d3ca782]
Login

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

Overview
Comment:Documentation of two-size lookaside.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256: 668d3ca7828e9ffa5499d7e908d93f8c6afbe53a1dd130c1e6f1493152756657
User & Date: drh 2020-01-18 00:56:52
Context
2020-01-18
22:24
Enhanced documentation for the TCL interface, and especially warnings about the importance of using the -directonly option for application-defined functions. check-in: 0d0e8a024d user: drh tags: trunk
00:56
Documentation of two-size lookaside. check-in: 668d3ca782 user: drh tags: trunk
2020-01-17
19:03
Add documentation for SQLITE_OMIT_GENERATED_COLUMNS check-in: df79d373f6 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/changes.in.

46
47
48
49
50
51
52




53
54
55
56
57
58
59
    new properties [SQLITE_INNOCUOUS] or [SQLITE_DIRECTONLY].
<li>Add new verbs to [sqlite3_vtab_config()] so that the [xConnect] method
    of virtual tables can declare the virtual table as
    [SQLITE_VTAB_INNOCUOUS] or [SQLITE_VTAB_DIRECTONLY].
<li>Faster response to [sqlite3_interrupt()].
<li>Added the [https://sqlite.org/src/file/ext/misc/uuid.c|uuid.c] extension module
    implementing functions for processing RFC-4122 UUIDs.




<li>The [legacy_file_format pragma] is deactivated.  It is now a no-op.  In its place,
    the [SQLITE_DBCONFIG_LEGACY_FILE_FORMAT] option to [sqlite3_db_config()] is
    provided.  The legacy_file_format pragma is deactivated because (1) it is
    rarely useful and (2) it is incompatible with [VACUUM] in schemas that have
    tables with both generated columns and descending indexes.
    Ticket [https://www.sqlite.org/src/info/6484e6ce678fffab|6484e6ce678fffab]
}







>
>
>
>







46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
    new properties [SQLITE_INNOCUOUS] or [SQLITE_DIRECTONLY].
<li>Add new verbs to [sqlite3_vtab_config()] so that the [xConnect] method
    of virtual tables can declare the virtual table as
    [SQLITE_VTAB_INNOCUOUS] or [SQLITE_VTAB_DIRECTONLY].
<li>Faster response to [sqlite3_interrupt()].
<li>Added the [https://sqlite.org/src/file/ext/misc/uuid.c|uuid.c] extension module
    implementing functions for processing RFC-4122 UUIDs.
<li>The [lookaside memory allocator] is enhanced to support two separate memory
    pools with different sized allocations in each pool.  This allows more memory
    allocations to be covered by lookaside while at the same time reducing the
    heap memory usage to 48KB per connection, down from 120KB.
<li>The [legacy_file_format pragma] is deactivated.  It is now a no-op.  In its place,
    the [SQLITE_DBCONFIG_LEGACY_FILE_FORMAT] option to [sqlite3_db_config()] is
    provided.  The legacy_file_format pragma is deactivated because (1) it is
    rarely useful and (2) it is incompatible with [VACUUM] in schemas that have
    tables with both generated columns and descending indexes.
    Ticket [https://www.sqlite.org/src/info/6484e6ce678fffab|6484e6ce678fffab]
}

Changes to pages/malloc.in.

589
590
591
592
593
594
595




































596
597
598
599
600
601
602
must point to at least sz*cnt bytes of memory.</p>

<p>The lookaside configuration can only be changed while there are
no outstanding lookaside allocations for the database connection.
Hence, the configuration should be set immediately after creating the 
database connection using [sqlite3_open()] (or equivalent) and before
evaluating any SQL statements on the connection.</p>





































<tcl>hd_fragment memstatus {memory statistics}</tcl>
<h2> Memory status</h2>

<p>By default, SQLite keeps statistics on its memory usage.  These
statistics are useful in helping to determine how much memory an
application really needs.  The statistics can also be used in







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







589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
must point to at least sz*cnt bytes of memory.</p>

<p>The lookaside configuration can only be changed while there are
no outstanding lookaside allocations for the database connection.
Hence, the configuration should be set immediately after creating the 
database connection using [sqlite3_open()] (or equivalent) and before
evaluating any SQL statements on the connection.</p>

<h3>Two-Size Lookaside</h3>

<p>
Beginning with SQLite version 3.31.0 ([dateof:3.31.0]),
lookaside supports two memory pools, each with a different size
slot.  The small-slot pool uses 128-byte slots and the large-slot
pool uses whatever size is specified by [SQLITE_DBCONFIG_LOOKASIDE]
(defaulting to 1200 bytes).  Splitting the pool in two like this
allows memory allocations to be covered by lookaside more often
while at the same time reducing per-database-connection heap usage
from 120KB down to 48KB.

<p>
Configuration continues to use the SQLITE_DBCONFIG_LOOKASIDE or
SQLITE_CONFIG_LOOKASIDE configuration options, as described above,
with parameters "sz" and "cnt".  The total heap space used for
lookaside continues to be sz*cnt bytes.  But the space is allocated
between the small-slot lookaside and big-slot lookaside, with
preference given to small-slot lookaside.  The total number of
slots will usually exceed "cnt", since "sz" is typically much
larger than the small-slot size of 128 bytes.

<p>
The default lookaside configuration has changed from 100 slots
of 1200 bytes each (120KB) to be 40 slots of 1200 bytes each
(48KB).  This space ends up being allocated as 93 slots of
128 bytes each and 30 slots of 1200 bytes each.  So more lookaside
slots are available but much less heap space is used.

<p>
The default lookaside configuration, the size of the small-slots,
and the details of how heap space is allocated between small-slots
and big-slots, are all subject to change from one release to the
next.


<tcl>hd_fragment memstatus {memory statistics}</tcl>
<h2> Memory status</h2>

<p>By default, SQLite keeps statistics on its memory usage.  These
statistics are useful in helping to determine how much memory an
application really needs.  The statistics can also be used in