diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/bt_conf.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/bt_conf.html')
| -rw-r--r-- | docs/programmer_reference/bt_conf.html | 604 |
1 files changed, 343 insertions, 261 deletions
diff --git a/docs/programmer_reference/bt_conf.html b/docs/programmer_reference/bt_conf.html index b270901d..98774713 100644 --- a/docs/programmer_reference/bt_conf.html +++ b/docs/programmer_reference/bt_conf.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="general_am_conf.html">Prev</a> </td> - <th width="60%" align="center">Chapter 2. - Access Method Configuration - </th> + <th width="60%" align="center">Chapter 2. Access Method Configuration </th> <td width="20%" align="right"> <a accesskey="n" href="hash_conf.html">Next</a></td> </tr> </table> @@ -47,7 +45,8 @@ </dt> <dt> <span class="sect2"> - <a href="bt_conf.html#am_conf_bt_prefix">Btree prefix comparison</a> + <a href="bt_conf.html#am_conf_bt_prefix">Btree prefix + comparison</a> </span> </dt> <dt> @@ -68,9 +67,10 @@ </dl> </div> <p> - There are a series of configuration tasks which you can perform when - using the Btree access method. They are described in the following sections. -</p> + There are a series of configuration tasks which you can + perform when using the Btree access method. They are described + in the following sections. + </p> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> @@ -79,25 +79,34 @@ </div> </div> </div> - <p>The Btree data structure is a sorted, balanced tree structure storing -associated key/data pairs. By default, the sort order is lexicographical, -with shorter keys collating before longer keys. The user can specify the -sort order for the Btree by using the <a href="../api_reference/C/dbset_bt_compare.html" class="olink">DB->set_bt_compare()</a> method.</p> - <p>Sort routines are passed pointers to keys as arguments. The keys are -represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures. The routine must return an integer -less than, equal to, or greater than zero if the first argument is -considered to be respectively less than, equal to, or greater than the -second argument. The only fields that the routines may examine in the -<a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures are <span class="bold"><strong>data</strong></span> and <span class="bold"><strong>size</strong></span> fields.</p> - <p>An example routine that might be used to sort integer keys in the database -is as follows:</p> + <p> + The Btree data structure is a sorted, balanced tree + structure storing associated key/data pairs. By default, the + sort order is lexicographical, with shorter keys collating + before longer keys. The user can specify the sort order for + the Btree by using the <a href="../api_reference/C/dbset_bt_compare.html" class="olink">DB->set_bt_compare()</a> method. + </p> + <p> + Sort routines are passed pointers to keys as arguments. The + keys are represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures. The routine must + return an integer less than, equal to, or greater than zero if + the first argument is considered to be respectively less than, + equal to, or greater than the second argument. The only fields + that the routines may examine in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures are + <span class="bold"><strong>data</strong></span> and <span class="bold"><strong>size</strong></span> fields. + </p> + <p> + An example routine that might be used to sort integer keys + in the database is as follows: + </p> <a id="prog_am2"></a> - <pre class="programlisting"> -int -compare_int(DB *dbp, const DBT *a, const DBT *b) + <pre class="programlisting">int +compare_int(DB *dbp, const DBT *a, const DBT *b, size_t *locp) { int ai, bi; + + locp = NULL; /* * Returns: * < 0 if a < b @@ -109,23 +118,29 @@ compare_int(DB *dbp, const DBT *a, const DBT *b) return (ai - bi); } </pre> - <p>Note that the data must first be copied into memory that is appropriately -aligned, as Berkeley DB does not guarantee any kind of alignment of the -underlying data, including for comparison routines. When writing -comparison routines, remember that databases created on machines of -different architectures may have different integer byte orders, for which -your code may need to compensate.</p> - <p>An example routine that might be used to sort keys based on the first -five bytes of the key (ignoring any subsequent bytes) is as follows:</p> + <p> + Note that the data must first be copied into memory that is + appropriately aligned, as Berkeley DB does not guarantee any + kind of alignment of the underlying data, including for + comparison routines. When writing comparison routines, + remember that databases created on machines of different + architectures may have different integer byte orders, for + which your code may need to compensate. + </p> + <p> + An example routine that might be used to sort keys based on + the first five bytes of the key (ignoring any subsequent + bytes) is as follows: + </p> <a id="prog_am3"></a> - <pre class="programlisting"> -int -compare_dbt(DB *dbp, const DBT *a, const DBT *b) + <pre class="programlisting">int +compare_dbt(DB *dbp, const DBT *a, const DBT *b, size_t *locp) { int len; u_char *p1, *p2; + locp = NULL; /* * Returns: * < 0 if a < b @@ -138,52 +153,71 @@ compare_dbt(DB *dbp, const DBT *a, const DBT *b) return (0); } </pre> - <p>All comparison functions must cause the keys in the database to be -well-ordered. The most important implication of being well-ordered is -that the key relations must be transitive, that is, if key A is less -than key B, and key B is less than key C, then the comparison routine -must also return that key A is less than key C.</p> - <p>It is reasonable for a comparison function to not examine an entire key -in some applications, which implies partial keys may be specified to the -Berkeley DB interfaces. When partial keys are specified to Berkeley DB, interfaces -which retrieve data items based on a user-specified key (for example, -<a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> and <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> with the <a href="../api_reference/C/dbcget.html#dbcget_DB_SET" class="olink">DB_SET</a> flag), will -modify the user-specified key by returning the actual key stored in the -database.</p> + <p> + All comparison functions must cause the keys in the database + to be well-ordered. The most important implication of being + well-ordered is that the key relations must be transitive, + that is, if key A is less than key B, and key B is less than + key C, then the comparison routine must also return that key A + is less than key C. + </p> + <p> + It is reasonable for a comparison function to not examine an + entire key in some applications, which implies partial keys + may be specified to the Berkeley DB interfaces. When partial + keys are specified to Berkeley DB, interfaces which retrieve + data items based on a user-specified key (for example, <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> + and <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> with the <a href="../api_reference/C/dbcget.html#dbcget_DB_SET" class="olink">DB_SET</a> flag), will modify the + user-specified key by returning the actual key stored in the + database. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> - <h3 class="title"><a id="am_conf_bt_prefix"></a>Btree prefix comparison</h3> + <h3 class="title"><a id="am_conf_bt_prefix"></a>Btree prefix + comparison</h3> </div> </div> </div> - <p>The Berkeley DB Btree implementation maximizes the number of keys that can be -stored on an internal page by storing only as many bytes of each key as -are necessary to distinguish it from adjacent keys. The prefix -comparison routine is what determines this minimum number of bytes (that -is, the length of the unique prefix), that must be stored. A prefix -comparison function for the Btree can be specified by calling -<a href="../api_reference/C/dbset_bt_prefix.html" class="olink">DB->set_bt_prefix()</a>.</p> - <p>The prefix comparison routine must be compatible with the overall -comparison function of the Btree, since what distinguishes any two keys -depends entirely on the function used to compare them. This means that -if a prefix comparison routine is specified by the application, a -compatible overall comparison routine must also have been specified.</p> - <p>Prefix comparison routines are passed pointers to keys as arguments. -The keys are represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures. The only fields -the routines may examine in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures are <span class="bold"><strong>data</strong></span> -and <span class="bold"><strong>size</strong></span> fields.</p> - <p>The prefix comparison function must return the number of bytes necessary -to distinguish the two keys. If the keys are identical (equal and equal -in length), the length should be returned. If the keys are equal up to -the smaller of the two lengths, then the length of the smaller key plus -1 should be returned.</p> - <p>An example prefix comparison routine follows:</p> + <p> + The Berkeley DB Btree implementation maximizes the number of + keys that can be stored on an internal page by storing only as + many bytes of each key as are necessary to distinguish it from + adjacent keys. The prefix comparison routine is what + determines this minimum number of bytes (that is, the length + of the unique prefix), that must be stored. A prefix + comparison function for the Btree can be specified by calling + <a href="../api_reference/C/dbset_bt_prefix.html" class="olink">DB->set_bt_prefix()</a>. + </p> + <p> + The prefix comparison routine must be compatible with the + overall comparison function of the Btree, since what + distinguishes any two keys depends entirely on the function + used to compare them. This means that if a prefix comparison + routine is specified by the application, a compatible overall + comparison routine must also have been specified. + </p> + <p> + Prefix comparison routines are passed pointers to keys as + arguments. The keys are represented as <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures. The + only fields the routines may examine in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures + are <span class="bold"><strong>data</strong></span> and <span class="bold"><strong>size</strong></span> fields. + </p> + <p> + The prefix comparison function must return the number of + bytes necessary to distinguish the two keys. If the keys are + identical (equal and equal in length), the length should be + returned. If the keys are equal up to the smaller of the two + lengths, then the length of the smaller key plus 1 should be + returned. + </p> + <p> + An example prefix comparison routine follows: + </p> <a id="prog_am4"></a> - <pre class="programlisting"> -size_t + <pre class="programlisting">size_t compare_prefix(DB *dbp, const DBT *a, const DBT *b) { @@ -207,8 +241,11 @@ compare_prefix(DB *dbp, const DBT *a, const DBT *b) return (b->size); } </pre> - <p>The usefulness of this functionality is data-dependent, but in some data -sets can produce significantly reduced tree sizes and faster search times.</p> + <p> + The usefulness of this functionality is data-dependent, but + in some data sets can produce significantly reduced tree sizes + and faster search times. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> @@ -218,38 +255,58 @@ sets can produce significantly reduced tree sizes and faster search times.</p> </div> </div> </div> - <p>The number of keys stored on each page affects the size of a Btree and -how it is maintained. Therefore, it also affects the retrieval and search -performance of the tree. For each Btree, Berkeley DB computes a maximum key -and data size. This size is a function of the page size and the fact that -at least two key/data pairs must fit on any Btree page. Whenever key or -data items exceed the calculated size, they are stored on overflow pages -instead of in the standard Btree leaf pages.</p> - <p>Applications may use the <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB->set_bt_minkey()</a> method to change the minimum -number of keys that must fit on a Btree page from two to another value. -Altering this value in turn alters the on-page maximum size, and can be -used to force key and data items which would normally be stored in the -Btree leaf pages onto overflow pages.</p> - <p>Some data sets can benefit from this tuning. For example, consider an -application using large page sizes, with a data set almost entirely -consisting of small key and data items, but with a few large items. By -setting the minimum number of keys that must fit on a page, the -application can force the outsized items to be stored on overflow pages. -That in turn can potentially keep the tree more compact, that is, with -fewer internal levels to traverse during searches.</p> - <p>The following calculation is similar to the one performed by the Btree -implementation. (The <span class="bold"><strong>minimum_keys</strong></span> value is multiplied by 2 -because each key/data pair requires 2 slots on a Btree page.)</p> + <p> + The number of keys stored on each page affects the size of a + Btree and how it is maintained. Therefore, it also affects the + retrieval and search performance of the tree. For each Btree, + Berkeley DB computes a maximum key and data size. This size is + a function of the page size and the fact that at least two + key/data pairs must fit on any Btree page. Whenever key or + data items exceed the calculated size, they are stored on + overflow pages instead of in the standard Btree leaf + pages. + </p> + <p> + Applications may use the <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB->set_bt_minkey()</a> method to change + the minimum number of keys that must fit on a Btree page from + two to another value. Altering this value in turn alters the + on-page maximum size, and can be used to force key and data + items which would normally be stored in the Btree leaf pages + onto overflow pages. + </p> + <p> + Some data sets can benefit from this tuning. For example, + consider an application using large page sizes, with a data + set almost entirely consisting of small key and data items, + but with a few large items. By setting the minimum number of + keys that must fit on a page, the application can force the + outsized items to be stored on overflow pages. That in turn + can potentially keep the tree more compact, that is, with + fewer internal levels to traverse during searches. + </p> + <p> + The following calculation is similar to the one performed by + the Btree implementation. (The <span class="bold"><strong>minimum_keys + </strong></span> value is multiplied by 2 because + each key/data pair requires 2 slots on a Btree page.) + </p> <pre class="programlisting">maximum_size = page_size / (minimum_keys * 2)</pre> - <p>Using this calculation, if the page size is 8KB and the default -<span class="bold"><strong>minimum_keys</strong></span> value of 2 is used, then any key or data items -larger than 2KB will be forced to an overflow page. If an application -were to specify a <span class="bold"><strong>minimum_key</strong></span> value of 100, then any key or data -items larger than roughly 40 bytes would be forced to overflow pages.</p> - <p>It is important to remember that accesses to overflow pages do not perform -as well as accesses to the standard Btree leaf pages, and so setting the -value incorrectly can result in overusing overflow pages and decreasing -the application's overall performance.</p> + <p> + Using this calculation, if the page size is 8KB and the + default <span class="bold"><strong>minimum_keys</strong></span> value of + 2 is used, then any key or data items larger than 2KB will be + forced to an overflow page. If an application were to specify + a <span class="bold"><strong>minimum_key</strong></span> value of 100, + then any key or data items larger than roughly 40 bytes would + be forced to overflow pages. + </p> + <p> + It is important to remember that accesses to overflow pages + do not perform as well as accesses to the standard Btree leaf + pages, and so setting the value incorrectly can result in + overusing overflow pages and decreasing the application's + overall performance. + </p> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> @@ -259,21 +316,28 @@ the application's overall performance.</p> </div> </div> </div> - <p>The Btree access method optionally supports retrieval by logical record -numbers. To configure a Btree to support record numbers, call the -<a href="../api_reference/C/dbset_flags.html" class="olink">DB->set_flags()</a> method with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> flag.</p> - <p>Configuring a Btree for record numbers should not be done lightly. -While often useful, it may significantly slow down the speed at which -items can be stored into the database, and can severely impact -application throughput. Generally it should be avoided in trees with -a need for high write concurrency.</p> - <p>To retrieve by record number, use the <a href="../api_reference/C/dbget.html#dbget_DB_SET_RECNO" class="olink">DB_SET_RECNO</a> flag to the -<a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> and <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> methods. The following is an example of -a routine that displays the data item for a Btree database created with -the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> option.</p> + <p> + The Btree access method optionally supports retrieval by + logical record numbers. To configure a Btree to support record + numbers, call the <a href="../api_reference/C/dbset_flags.html" class="olink">DB->set_flags()</a> method with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> + flag. + </p> + <p> + Configuring a Btree for record numbers should not be done + lightly. While often useful, it may significantly slow down + the speed at which items can be stored into the database, and + can severely impact application throughput. Generally it + should be avoided in trees with a need for high write + concurrency. + </p> + <p> + To retrieve by record number, use the <a href="../api_reference/C/dbget.html#dbget_DB_SET_RECNO" class="olink">DB_SET_RECNO</a> flag + to the <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> and <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> methods. The following is an + example of a routine that displays the data item for a Btree + database created with the <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_RECNUM" class="olink">DB_RECNUM</a> option. + </p> <a id="prog_am5"></a> - <pre class="programlisting"> -int + <pre class="programlisting">int rec_display(DB *dbp, db_recno_t recno) { @@ -292,12 +356,14 @@ rec_display(DB *dbp, db_recno_t recno) return (0); } </pre> - <p>To determine a key's record number, use the <a href="../api_reference/C/dbcget.html#dbcget_DB_GET_RECNO" class="olink">DB_GET_RECNO</a> flag -to the <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> method. The following is an example of a routine that -displays the record number associated with a specific key.</p> + <p> + To determine a key's record number, use the <a href="../api_reference/C/dbcget.html#dbcget_DB_GET_RECNO" class="olink">DB_GET_RECNO</a> + flag to the <a href="../api_reference/C/dbcget.html" class="olink">DBC->get()</a> method. The following is an example of a + routine that displays the record number associated with a + specific key. + </p> <a id="prog_am6"></a> - <pre class="programlisting"> -int + <pre class="programlisting">int recno_display(DB *dbp, char *keyvalue) { @@ -355,55 +421,59 @@ err: /* Close the cursor. */ </div> </div> </div> - <p> - The Btree access method supports the automatic compression of key/data - pairs upon their insertion into the database. The key/data pairs are - decompressed before they are returned to the application, making an - application's interaction with a compressed database identical to that - for a non-compressed database. To configure Berkeley DB for - compression, call the <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB->set_bt_compress()</a> method and specify custom - compression and decompression functions. If <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB->set_bt_compress()</a> is - called with NULL compression and decompression functions, Berkeley DB - will use its default compression functions. -</p> + <p> + The Btree access method supports the automatic compression + of key/data pairs upon their insertion into the database. The + key/data pairs are decompressed before they are returned to + the application, making an application's interaction with a + compressed database identical to that for a non-compressed + database. To configure Berkeley DB for compression, call the + <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB->set_bt_compress()</a> method and specify custom compression and + decompression functions. If <a href="../api_reference/C/dbset_bt_compress.html" class="olink">DB->set_bt_compress()</a> is called with + NULL compression and decompression functions, Berkeley DB will + use its default compression functions. + </p> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> - <p> - Compression only works with the Btree access method, and then only - so long as your database is not configured for unsorted duplicates. - </p> + <p> + Compression only works with the Btree access method, + and then only so long as your database is not configured + for unsorted duplicates. + </p> </div> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3> - <p> - The default compression function is not guaranteed to reduce the - size of the on-disk database in every case. It has been tested - and shown to work well with English-language text. Of course, in - order to determine if the default compression algorithm is beneficial - for your application, it is important to test both the final size - and the performance using a representative set of data and access - patterns. - </p> + <p> + The default compression function is not guaranteed to + reduce the size of the on-disk database in every case. It + has been tested and shown to work well with + English-language text. Of course, in order to determine if + the default compression algorithm is beneficial for your + application, it is important to test both the final size + and the performance using a representative set of data and + access patterns. + </p> </div> <p> - The default compression function performs prefix compression on each - key added to the database. This means that, for a key - <span class="emphasis"><em>n</em></span> bytes in length, the first - <span class="emphasis"><em>i</em></span> bytes that match the first - <span class="emphasis"><em>i</em></span> bytes of the previous key exactly are omitted - and only the final <span class="emphasis"><em>n-i</em></span> bytes are stored in the - database. If the bytes of key being stored match the bytes of the - previous key exactly, then the same prefix compression algorithm is - applied to the data value being stored. To use Berkeley DB's default - compression behavior, both the default compression and decompression - functions must be used. -</p> + The default compression function performs prefix + compression on each key added to the database. This means + that, for a key <span class="emphasis"><em>n</em></span> bytes in length, the + first <span class="emphasis"><em>i</em></span> bytes that match the first + <span class="emphasis"><em>i</em></span> bytes of the previous key exactly + are omitted and only the final <span class="emphasis"><em>n-i</em></span> bytes + are stored in the database. If the bytes of key being stored + match the bytes of the previous key exactly, then the same + prefix compression algorithm is applied to the data value + being stored. To use Berkeley DB's default compression + behavior, both the default compression and decompression + functions must be used. + </p> <p> - For example, to configure your database for default compression: -</p> + For example, to configure your database for default + compression: + </p> <a id="prog_am7"></a> - <pre class="programlisting"> - DB *dbp = NULL; + <pre class="programlisting">DB *dbp = NULL; DB_ENV *envp = NULL; u_int32_t db_flags; const char *file_name = "mydb.db"; @@ -441,60 +511,64 @@ err: /* Close the cursor. */ <div class="titlepage"> <div> <div> - <h4 class="title"><a id="am_conf_bt_custom_compress"></a>Custom compression</h4> + <h4 class="title"><a id="am_conf_bt_custom_compress"></a>Custom + compression</h4> </div> </div> </div> <p> - An application wishing to perform its own compression may supply a - compression and decompression function which will be called instead of - Berkeley DB's default functions. The compression function is - passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: -</p> + An application wishing to perform its own compression + may supply a compression and decompression function which + will be called instead of Berkeley DB's default functions. + The compression function is passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: + </p> <div class="itemizedlist"> <ul type="disc"> <li> - <p> - The key and data immediately preceeding the key/data pair - that is being stored. - </p> + <p> + The key and data immediately preceeding the + key/data pair that is being stored. + </p> </li> <li> <p> - The key and data being stored in the tree. - </p> + The key and data being stored in the tree. + </p> </li> <li> - <p> - The buffer where the compressed data should be written. - </p> + <p> + The buffer where the compressed data should be + written. + </p> </li> </ul> </div> + <p> + The total size of the buffer used to store the + compressed data is identified in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s + <code class="literal">ulen</code> field. If the compressed data + cannot fit in the buffer, the compression function should + store the amount of space needed in <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s + <code class="literal">size</code> field and then return + <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will + subsequently re-call the compression function with the + required amount of space allocated in the compression data + buffer. + </p> + <p> + Multiple compressed key/data pairs will likely be + written to the same buffer and the compression function + should take steps to ensure it does not overwrite data. + </p> <p> - The total size of the buffer used to store the compressed data is - identified in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s <code class="literal">ulen</code> field. If the - compressed data cannot fit in the buffer, the compression function - should store the amount of space needed in <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s - <code class="literal">size</code> field and then return - <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will subsequently - re-call the compression function with the required amount of space - allocated in the compression data buffer. - </p> - <p> - Multiple compressed key/data pairs will likely be written to the - same buffer and the compression function should take steps to - ensure it does not overwrite data. - </p> - <p> - For example, the following code fragments illustrate the use of a custom - compression routine. This code is actually a much simplified - example of the default compression provided by Berkeley DB. It does - simple prefix compression on the key part of the data. - </p> + For example, the following code fragments illustrate + the use of a custom compression routine. This code is + actually a much simplified example of the default + compression provided by Berkeley DB. It does simple prefix + compression on the key part of the data. + </p> <a id="prog_am8"></a> - <pre class="programlisting"> - int compress(DB *dbp, const DBT *prevKey, const DBT *prevData, + <pre class="programlisting">int compress(DB *dbp, const DBT *prevKey, const DBT *prevData, const DBT *key, const DBT *data, DBT *dest) { u_int8_t *dest_data_ptr; @@ -538,49 +612,53 @@ err: /* Close the cursor. */ return (0); } </pre> <p> - The corresponding decompression function is likewise passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: - </p> + The corresponding decompression function is likewise + passed five <a href="../api_reference/C/dbt.html" class="olink">DBT</a> structures: + </p> <div class="itemizedlist"> <ul type="disc"> <li> - <p> - The key and data <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s immediately preceding the - decompressed key and data. - </p> + <p> + The key and data <a href="../api_reference/C/dbt.html" class="olink">DBT</a>s immediately preceding + the decompressed key and data. + </p> </li> <li> - <p> - The compressed data from the database. - </p> + <p> + The compressed data from the database. + </p> </li> <li> - <p> - One to store the decompressed key and another one for the - decompressed data. - </p> + <p> + One to store the decompressed key and another + one for the decompressed data. + </p> </li> </ul> </div> + <p> + Because the compression of <code class="literal">record X</code> + relies upon <code class="literal">record X-1</code>, the + decompression function can be called repeatedly to + linearally decompress a set of records stored in the + compressed buffer. + </p> <p> - Because the compression of <code class="literal">record X</code> relies upon - <code class="literal">record X-1</code>, the decompression function can be - called repeatedly to linearally decompress a set of records stored - in the compressed buffer. - </p> - <p> - The total size of the buffer available to store the decompressed data is - identified in the destination <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s <code class="literal">ulen</code> field. If the - decompressed data cannot fit in the buffer, the decompression function - should store the amount of space needed in the destination <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s - <code class="literal">size</code> field and then return - <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will subsequently - re-call the decompression function with the required amount of space - allocated in the decompression data buffer. - </p> + The total size of the buffer available to store the + decompressed data is identified in the destination <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s + <code class="literal">ulen</code> field. If the decompressed + data cannot fit in the buffer, the decompression function + should store the amount of space needed in the destination + <a href="../api_reference/C/dbt.html" class="olink">DBT</a>'s <code class="literal">size</code> field and then return + <code class="literal">DB_BUFFER_SMALL</code>. Berkeley DB will + subsequently re-call the decompression function with the + required amount of space allocated in the decompression + data buffer. + </p> <p> - For example, the decompression routine that corresponds to the - example compression routine provided above is: -</p> + For example, the decompression routine that corresponds + to the example compression routine provided above is: + </p> <a id="prog_am9"></a> <pre class="programlisting">int decompress(DB *dbp, const DBT *prevKey, const DBT *prevData, DBT *compressed, DBT *destKey, DBT *destData) @@ -642,46 +720,49 @@ err: /* Close the cursor. */ <div class="titlepage"> <div> <div> - <h4 class="title"><a id="idm1755952"></a>Programmer Notes</h4> + <h4 class="title"><a id="idm2102248"></a>Programmer Notes</h4> </div> </div> </div> - <p> - As you use compression with your databases, be aware of the - following: - </p> + <p> + As you use compression with your databases, be aware of + the following: + </p> <div class="itemizedlist"> <ul type="disc"> <li> - <p> - Compression works by placing key/data pairs from a single - database page into a single block of compressed data. This is true - whether you use DB's default compression, or you write - your own compression. Because all of key/data data is - placed in a single block of memory, you cannot decompress - data unless you have decompressed everything that came - before it in the block. That is, you cannot decompress item - <span class="emphasis"><em>n</em></span> in the data block, unless you also - decompress items <span class="emphasis"><em>0</em></span> through - <span class="emphasis"><em>n-1</em></span>. - </p> + <p> + Compression works by placing key/data pairs + from a single database page into a single block of + compressed data. This is true whether you use + DB's default compression, or you write your + own compression. Because all of key/data data is + placed in a single block of memory, you cannot + decompress data unless you have decompressed + everything that came before it in the block. That + is, you cannot decompress item + <span class="emphasis"><em>n</em></span> in the data block, + unless you also decompress items + <span class="emphasis"><em>0</em></span> through + <span class="emphasis"><em>n-1</em></span>. + </p> </li> <li> <p> - If you increase the minimum number of key/data pairs placed - on a Btree leaf page (using <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB->set_bt_minkey()</a>), you will - decrease your seek times on a compressed database. However, - this will also decrease the effectiveness of the - compression. - </p> + If you increase the minimum number of key/data + pairs placed on a Btree leaf page (using + <a href="../api_reference/C/dbset_bt_minkey.html" class="olink">DB->set_bt_minkey()</a>), you will decrease your seek + times on a compressed database. However, this will + also decrease the effectiveness of the + compression. + </p> </li> <li> - <p> - Compressed databases are fastest if bulk load is used to - add data to them. See - <a class="xref" href="am_misc_bulk.html" title="Retrieving and updating records in bulk">Retrieving and updating records in bulk</a> - for information on using bulk load. - </p> + <p> + Compressed databases are fastest if bulk load + is used to add data to them. See <a class="xref" href="am_misc_bulk.html" title="Retrieving and updating records in bulk">Retrieving and updating records in bulk</a> for information + on using bulk load. + </p> </li> </ul> </div> @@ -703,7 +784,8 @@ err: /* Close the cursor. */ <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> - <td width="40%" align="right" valign="top"> Hash access method specific configuration</td> + <td width="40%" align="right" valign="top"> Hash access method specific + configuration</td> </tr> </table> </div> |