|
|
|
This option enables batch record retrieval to improve performance of consecutive sequential reads. This is achieved by retrieving a given number of records (specified by the records attribute) from the server to the client side at the second consecutive sequential read operation. The next sequential read operations do not need to contact the server to retrieve the records as the records are now cached on the client side. Once all the records in the client cache are processed, the next block of records is requested to the server.
By default, the records cached on the client side cannot be updated by other users (the allowwriters attribute overrides this default). This avoids situations in which the cached records do not match the records on the server.
The records are prefetched during the second subsequent call to an operation that reads the next record (Get Next) or the previous record (Get Previous). The Get Next or the Get Previous operation performs as follows when <prefetch> is active:
BTRV Command |
Action |
|---|---|
Get Key |
|
Get Next |
Reads one record from the server, therefore performs as normal. |
Get Next |
Reads n records from the server, but returns only one record, therefore performs worse than normal. |
Get Next |
Reads one record from client's prefetch buffer, therefore performs very fast. |
Get Next |
Reads one record from client's prefetch buffer, therefore performs very fast. |
Get Next |
... |
The pattern described above also applies to a series of READ PREVIOUS calls.
Prefetching records improves performance of sequential reads in environments where the client and server reside on different systems connected with a network. In such environments any request from the client to the server is sent over the network which is generally a time-expensive operation. It is advisable to configure c-tree so that <prefetch> is enabled only on files were large numbers of Get Next operations are performed, as shown in the examples below.
The default value of <prefetch records="10"> has been demonstrated to be optimal for most cases. However, if you want to fine tune the value, please make sure that it matches (as closely as possible) the number of subsequent Get Next operations performed by your application. Setting <prefetch records> to a larger number will result in reading records from disk that will never be returned to the application which may neutralize the performance gain of prefetching records.
Please notice that any Get Record operation in the middle of a Get Next or Get Previous sequence invalidates the prefetched records causing the prefetch logic to restart at the next Get Next or Get Previous operation.
The number of records to prefetch is defined by the records attribute. The size of the prefetch buffer is determined by the record size and the number of records:
prefetch_buffer_size = record_size * <prefetch_records>
Accepted Values
Value |
Effect |
Synonyms |
|---|---|---|
yes |
Enable record prefetch. |
y, true, on, 1 |
no |
Disable record prefetch. This is the default value. |
n, false, off, 0 |
Attributes
Attribute |
Values |
Description |
Synonyms |
|---|---|---|---|
records |
n = number of records |
Indicates the number of records to prefetch. This value is set to 10 by default. Note: Increasing this setting too far might cause a slow down, so adjust it wisely |
recs |
allowwriters |
yes, y, true, on, 1 or n, false, off, 0 |
When a set of records is prefetched, the prefetched records are locked with a read lock that allows other users to read them but prevents other users from updating them. When this attribute is enabled, the read lock is not used so that other users can alter the prefetched records. This attribute is disabled by default (prefetch allowwriters="no"). See Notes about <prefetch allowwriters> below. |
writers |
Notes about <prefetch allowwriters>
If you are calling Get Next or Get Previous with any locking options, then <prefetch allowwriters> has basically no effect as all the prefetched records will be locked as a result of the requested lock options of the Get Next calls.
If you are calling Get Next or Get Previous without any locking options, then <prefetch allowwriters> is significant. With allowwriters=no (the default), the prefetched records are locked with a read lock type that allows other users to read them but prevents other users from updating them. Setting allowwriters=yes allows other users to read and write the prefetched records, which may cause the user reading the prefetched record to retrieve a record that has been changed or even deleted by another user.
Note: It is the programmer's responsibility to ensure that the application does not have issues with prefetched records that have been modified. Enable allowwrites only when data is not critical and/or seldom changes. For example, a list of countries or dealer locations may not change frequently, so prefetched records will rarely be out-of-date.
Do not enable allowwrites if the data is critical and/or frequently changing. For example, account balances or line items on an open order need to be up-to-date.
Examples
To enable <prefetch> and set the number of prefetched records to 50:
<prefetch records="50">yes</prefetch>
To enable prefetch and allow prefetched records to be modified by other users:
<prefetch allowwriters="yes">yes</prefetch>
To configure c-tree so that <prefetch> is enabled only on specific files:
<config>
<file/>
<file name="specific_file">
<prefetch>yes</prefetch>
</file>
</config>
The configuration above turns on <prefetch> only for specific_file, leaving it off all other files.
