Documentation Source Text

Check-in [c8b24bb8c6]
Login

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

Overview
Comment:Update the change log for 3.7.17. Fix typos in the memory-mapped I/O documentation.
Downloads: Tarball | ZIP archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: c8b24bb8c61af7a43b255316607259b7e152b638
User & Date: drh 2013-04-26 19:35:34.618
Context
2013-04-27
12:01
Updates to documentation, especially the C API introduction. (check-in: f0275a9b47 user: drh tags: trunk)
2013-04-26
19:35
Update the change log for 3.7.17. Fix typos in the memory-mapped I/O documentation. (check-in: c8b24bb8c6 user: drh tags: trunk)
15:21
Update the change log for 3.7.17 after reviewing the timeline. (check-in: 7e7024c429 user: drh tags: trunk)
Changes
Unified Diff Ignore Whitespace Patch
Changes to pages/changes.in.
︙︙
73
74
75
76
77
78
79


80
81
82
83
84
85
86

    for further information about what that extension does.
<li>Added the [fts3tokenize virtual table] to the [full-text search] logic.
<li>Query planner enhancement: Use the transitive property of constraints
    to move constraints into the outer loops of a join whenever possible,
    thereby reducing the amount of work that needs to occur in inner loops.
<li>Enhance the [fts4aux] virtual table so that a TEMP fts4aux table can reference
    an [FTS4] table in main database.


<li>Bug fix:
    Only consider AS names from the result set as candidates for resolving
    identifiers in the WHERE clause if there are no other matches. In the 
    ORDER BY clause, AS names take priority over any column names.
    Ticket [http://www.sqlite.org/src/info/2500cdb9be05 | 2500cdb9be05]
<li>Bug fix: 
    Prevent excessive stack usage in the [full-text search] engine when processing








>
>








73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

    for further information about what that extension does.
<li>Added the [fts3tokenize virtual table] to the [full-text search] logic.
<li>Query planner enhancement: Use the transitive property of constraints
    to move constraints into the outer loops of a join whenever possible,
    thereby reducing the amount of work that needs to occur in inner loops.
<li>Enhance the [fts4aux] virtual table so that a TEMP fts4aux table can reference
    an [FTS4] table in main database.
<li>Discontinue the use of posix_fallocate() on unix, as it does not work on all
    filesystems.
<li>Bug fix:
    Only consider AS names from the result set as candidates for resolving
    identifiers in the WHERE clause if there are no other matches. In the 
    ORDER BY clause, AS names take priority over any column names.
    Ticket [http://www.sqlite.org/src/info/2500cdb9be05 | 2500cdb9be05]
<li>Bug fix: 
    Prevent excessive stack usage in the [full-text search] engine when processing
︙︙
Changes to pages/mmap.in.
︙︙
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

a call to xFetch() returns a NULL pointer (indicating that the requested
page is not currently mapped into the applications address space) then
SQLite silently falls back to using xRead().  An error is only reported
if xRead() also fails.</p>

<p>When updating the database file, SQLite always makes a copy of the
page content into heap memory before modifying the page.  This is necessary
since the changes are not suppose to be visible to other processes until
after the transaction commits and so the changes must occur in private memory.
After all needed changes are completed, xWrite() is used to move the content
back into the database file.  The current xWrite() implementions for both
unix and windows check to see if section of the file being written is 
mapped into the applications address space, and if it is the write operation
is implemented using memcpy() rather than invoking a "write()" system call,
but that is just an implementation detail.  A memory copy occurs either way.
So the use of memory mapped I/O does not significantly change the performance
of database changes.  Memory mapped I/O is mostly a benefit for queries.</p>

<h2>Configuring Memory-Mapped I/O</h2>

<p>The "mmap_size" is the maximum number of bytes of the database file that
SQLite will try to map into the process address space at one time.  The
mmap_size applies separately to each database file, so the total amount
of process address space that could potentially be used is the mmap_size
times the number of open database files.</p>

<p>To activate memory-mapped I/O, an application an set the mmap_size to some
large value.  For example:</p>

<blockquote><pre>
PRAGMA mmap_size=268435456;
</pre></blockquote>

<p>To disable memory-mapped I/O, simply set the mmap_size to zero:</p>

<blockquote><pre>
PRAGMA mmap_size=0;
</pre></blockquote>

<p>If mmap_size is set to N then all current implementations map the first
N bytes of the database file and use legacy xRead() calls for any content
beyond N bytes.  If the database file is smaller then N bytes, then the entire
file is mapped.  In the future, new OS interfaces could, in theory, map
regions of the file other than the first N bytes, but no such 
implementation currently exists.</p>

<p>The mmap_size is set separately for each database file using the
"[PRAGMA mmap_size]" statement.  The usual default mmap_size is zero,
meaning that memory mapped I/O is disabled by default.  However, the








|


|















|














|








83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

a call to xFetch() returns a NULL pointer (indicating that the requested
page is not currently mapped into the applications address space) then
SQLite silently falls back to using xRead().  An error is only reported
if xRead() also fails.</p>

<p>When updating the database file, SQLite always makes a copy of the
page content into heap memory before modifying the page.  This is necessary
since the changes are not supposed to be visible to other processes until
after the transaction commits and so the changes must occur in private memory.
After all needed changes are completed, xWrite() is used to move the content
back into the database file.  The current xWrite() implementations for both
unix and windows check to see if section of the file being written is 
mapped into the applications address space, and if it is the write operation
is implemented using memcpy() rather than invoking a "write()" system call,
but that is just an implementation detail.  A memory copy occurs either way.
So the use of memory mapped I/O does not significantly change the performance
of database changes.  Memory mapped I/O is mostly a benefit for queries.</p>

<h2>Configuring Memory-Mapped I/O</h2>

<p>The "mmap_size" is the maximum number of bytes of the database file that
SQLite will try to map into the process address space at one time.  The
mmap_size applies separately to each database file, so the total amount
of process address space that could potentially be used is the mmap_size
times the number of open database files.</p>

<p>To activate memory-mapped I/O, an application can set the mmap_size to some
large value.  For example:</p>

<blockquote><pre>
PRAGMA mmap_size=268435456;
</pre></blockquote>

<p>To disable memory-mapped I/O, simply set the mmap_size to zero:</p>

<blockquote><pre>
PRAGMA mmap_size=0;
</pre></blockquote>

<p>If mmap_size is set to N then all current implementations map the first
N bytes of the database file and use legacy xRead() calls for any content
beyond N bytes.  If the database file is smaller than N bytes, then the entire
file is mapped.  In the future, new OS interfaces could, in theory, map
regions of the file other than the first N bytes, but no such 
implementation currently exists.</p>

<p>The mmap_size is set separately for each database file using the
"[PRAGMA mmap_size]" statement.  The usual default mmap_size is zero,
meaning that memory mapped I/O is disabled by default.  However, the
︙︙