#include <db.h>
DB->set_slice_callback(DB *db,
int (*func)(const DB *db, const DBT *key, DBT *slice));
The DB->set_slice_callback() method
is optionally used to identify slices for applications using a
sliced environment. The callback identifies the portion of a
record's key that is used to allocate records across slices. This
is the slice-relevant portion of the key. If
no callback is specified, then the entire key is used to allocate
records across slices.
The DB->set_slice_callback() method
must be called on an opened database handle. Changing this callback
after the database has been created results in undefined behavior.
The DB->set_backup_callbacks()
method returns a non-zero error value on failure and 0 on success.
The func parameter is the function used to determine which part of a key is slice relevant.
This function takes three parameters:
db
The db parameter is the sliced database for which the callback is set.
key
The key parameter is the source of the slice specification fields. That is, this is the key portion of the database's records. Some portion of this key is used to determine slice location, and that portion of the key is determined by the function implemented by this callback.
slice
The slice parameter is the DBT into which the slice-relevant portion of the key will be written. This DBT is user-owned.
You should zero this
DBT, with
the exception of the size and
data fields. When initializing
the structure, set
size to DB_SLICE_BUFLEN, and
data to the address of a 32-bit
word aligned buffer of DB_SLICE_BUFLEN
bytes.
Within the context of the callback, you can set these two fields in the following ways:
If the slice-relevant portion of the key is one contiguous
region, the set data to the first
relevant byte in that region, and size
to the number of significant bytes. Change no other
fields.
If the slice-relevant portion of the key is more than one
contiguous region, then calculate the total size required
to hold the slice-relevant data. If this total size is
less than DB_SLICE_BUFLEN, then leave
the initialized buffer unchanged. If the total size is
greater than DB_SLICE_BUFLEN, then:
Allocate enough memory to contain all of the
slice-relevant data. By default,
malloc() is used to allocate
memory. However, if your application configured a
custom memory allocator using
DB_ENV->set_alloc()
or db_env_set_func_malloc,
then use that function.
Set the flags parameter to
DB_DBT_APPMALLOC. DB will
deallocate the memory before returning from the
API call, using the free function corresponding
to the allocator just used.
Once you have created a large enough buffer, set the slice DBT handle's size to the new buffer's size.
After that, concatenate all of the slice-relevant data together into the newly created buffer.
Be aware that the slice DBT handle's size can be zero, in which case the record will be placed in slice 0. Also, this size may be larger than the key's size, if it is appropriate for your application.