Type Alias WT_CURSOR 

pub type WT_CURSOR = __wt_cursor;

A WT_CURSOR handle is the interface to a cursor.

Cursors allow data to be searched, iterated and modified, implementing the CRUD (create, read, update and delete) operations. Cursors are opened in the context of a session. If a transaction is started, cursors operate in the context of the transaction until the transaction is resolved.

Raw data is represented by key/value pairs of WT_ITEM structures, but cursors can also provide access to fields within the key and value if the formats are described in the WT_SESSION::create method.

In the common case, a cursor is used to access records in a table. However, cursors can be used on subsets of tables (such as a single column or a projection of multiple columns), as an interface to statistics, configuration data or application-specific data sources. See WT_SESSION::open_cursor for more information.

Thread safety: A WT_CURSOR handle is not usually shared between threads, see @ref threads for more information.

Aliased Type

#[repr(C)]
pub struct WT_CURSOR {

    pub session: *mut __wt_session,
    pub uri: *const i8,
    pub key_format: *const i8,
    pub value_format: *const i8,
    pub get_key: Option<unsafe extern "C" fn(*mut __wt_cursor, ...) -> i32>,
    pub get_value: Option<unsafe extern "C" fn(*mut __wt_cursor, ...) -> i32>,
    pub set_key: Option<unsafe extern "C" fn(*mut __wt_cursor, ...)>,
    pub set_value: Option<unsafe extern "C" fn(*mut __wt_cursor, ...)>,
    pub compare: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_cursor, *mut i32) -> i32>,
    pub equals: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_cursor, *mut i32) -> i32>,
    pub next: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub prev: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub reset: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub search: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub search_near: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut i32) -> i32>,
    pub insert: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub modify: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_modify, i32) -> i32>,
    pub update: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub remove: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub reserve: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub close: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub reconfigure: Option<unsafe extern "C" fn(*mut __wt_cursor, *const i8) -> i32>,
    pub cache: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>,
    pub reopen: Option<unsafe extern "C" fn(*mut __wt_cursor, bool) -> i32>,
    pub uri_hash: u64,
    pub q: __wt_cursor__bindgen_ty_1,
    pub recno: u64,
    pub raw_recno_buf: [u8; 9],
    pub json_private: *mut c_void,
    pub lang_private: *mut c_void,
    pub key: __wt_item,
    pub value: __wt_item,
    pub saved_err: i32,
    pub internal_uri: *const i8,
    pub flags: u32,
}

Fields

session: *mut __wt_session

< The session handle for this cursor.

uri: *const i8

The name of the data source for the cursor, matches the \c uri parameter to WT_SESSION::open_cursor used to open the cursor.

key_format: *const i8

The format of the data packed into key items. See @ref packing for details. If not set, a default value of “u” is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

value_format: *const i8

The format of the data packed into value items. See @ref packing for details. If not set, a default value of “u” is assumed, and applications must use WT_ITEM structures to manipulate untyped byte arrays.

get_key: Option<unsafe extern "C" fn(*mut __wt_cursor, ...) -> i32>

@name Data access @{ / /*! Get the key for the current record.

@snippet ex_all.c Get the cursor’s string key

@snippet ex_all.c Get the cursor’s record number key

@param cursor the cursor handle @param … pointers to hold key fields corresponding to WT_CURSOR::key_format. @errors

get_value: Option<unsafe extern "C" fn(*mut __wt_cursor, ...) -> i32>

Get the value for the current record.

@snippet ex_all.c Get the cursor’s string value

@snippet ex_all.c Get the cursor’s raw value

@param cursor the cursor handle @param … pointers to hold value fields corresponding to WT_CURSOR::value_format. @errors

set_key: Option<unsafe extern "C" fn(*mut __wt_cursor, ...)>

Set the key for the next operation.

@snippet ex_all.c Set the cursor’s string key

@snippet ex_all.c Set the cursor’s record number key

@param cursor the cursor handle @param … key fields corresponding to WT_CURSOR::key_format.

If an error occurs during this operation, a flag will be set in the cursor, and the next operation to access the key will fail. This simplifies error handling in applications.

set_value: Option<unsafe extern "C" fn(*mut __wt_cursor, ...)>

Set the value for the next operation.

@snippet ex_all.c Set the cursor’s string value

@snippet ex_all.c Set the cursor’s raw value

@param cursor the cursor handle @param … value fields corresponding to WT_CURSOR::value_format.

If an error occurs during this operation, a flag will be set in the cursor, and the next operation to access the value will fail. This simplifies error handling in applications.

compare: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_cursor, *mut i32) -> i32>

@name Cursor positioning @{ / /*! Return the ordering relationship between two cursors: both cursors must have the same data source and have valid keys. (When testing only for equality, WT_CURSOR::equals may be faster.)

@snippet ex_all.c Cursor comparison

@param cursor the cursor handle @param other another cursor handle @param comparep the status of the comparison: < 0 if cursor refers to a key that appears before other, 0 if the cursors refer to the same key, and > 0 if cursor refers to a key that appears after other. @errors

equals: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_cursor, *mut i32) -> i32>

Return the ordering relationship between two cursors, testing only for equality: both cursors must have the same data source and have valid keys.

@snippet ex_all.c Cursor equality

@param cursor the cursor handle @param other another cursor handle @param[out] equalp the status of the comparison: 1 if the cursors refer to the same key, otherwise 0. @errors

next: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Return the next record.

@snippet ex_all.c Return the next record

@param cursor the cursor handle @errors

prev: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Return the previous record.

@snippet ex_all.c Return the previous record

@param cursor the cursor handle @errors

reset: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Reset the cursor. Any resources held by the cursor are released, and the cursor’s key and position are no longer valid. Subsequent iterations with WT_CURSOR::next will move to the first record, or with WT_CURSOR::prev will move to the last record.

In the case of a statistics cursor, resetting the cursor refreshes the statistics information returned.

@snippet ex_all.c Reset the cursor

@param cursor the cursor handle @errors

search: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Return the record matching the key. The key must first be set.

@snippet ex_all.c Search for an exact match

On success, the cursor ends positioned at the returned record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the record has been retrieved and the cursor no longer needs that position.

@param cursor the cursor handle @errors

search_near: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut i32) -> i32>

Return the record matching the key if it exists, or an adjacent record. An adjacent record is either the smallest record larger than the key or the largest record smaller than the key (in other words, a logically adjacent key).

The key must first be set.

An example of a search for an exact or adjacent match:

@snippet ex_all.c Search for an exact or adjacent match

An example of a forward scan through the table, where all keys greater than or equal to a specified prefix are included in the scan:

@snippet ex_all.c Forward scan greater than or equal

An example of a backward scan through the table, where all keys less than a specified prefix are included in the scan:

@snippet ex_all.c Backward scan less than

On success, the cursor ends positioned at the returned record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the record has been retrieved and the cursor no longer needs that position.

@param cursor the cursor handle @param exactp the status of the search: 0 if an exact match is found, < 0 if a smaller key is returned, > 0 if a larger key is returned @errors

insert: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

@name Data modification @{ / /*! Insert a record and optionally update an existing record.

If the cursor was configured with “overwrite=true” (the default), both the key and value must be set; if the record already exists, the key’s value will be updated, otherwise, the record will be inserted.

@snippet ex_all.c Insert a new record or overwrite an existing record

If the cursor was not configured with “overwrite=true”, both the key and value must be set and the record must not already exist; the record will be inserted.

@snippet ex_all.c Insert a new record and fail if the record exists

If a cursor with record number keys was configured with “append=true” (not the default), the value must be set; a new record will be appended and the record number set as the cursor key value.

@snippet ex_all.c Insert a new record and assign a record number

The cursor ends with no position, and a subsequent call to the WT_CURSOR::next (WT_CURSOR::prev) method will iterate from the beginning (end) of the table.

If the cursor does not have record number keys or was not configured with “append=true”, the cursor ends with no key set and a subsequent call to the WT_CURSOR::get_key method will fail. The cursor ends with no value set and a subsequent call to the WT_CURSOR::get_value method will fail.

Inserting a new record after the current maximum record in a fixed-length bit field column-store (that is, a store with an ‘r’ type key and ‘t’ type value) may implicitly create the missing records as records with a value of 0.

When loading a large amount of data into a new object, using a cursor with the \c bulk configuration string enabled and loading the data in sorted order will be much faster than doing out-of-order inserts. See @ref tune_bulk_load for more information.

The maximum length of a single column stored in a table is not fixed (as it partially depends on the underlying file configuration), but is always a small number of bytes less than 4GB.

@param cursor the cursor handle @errors In particular, if \c overwrite=false is configured and a record with the specified key already exists, ::WT_DUPLICATE_KEY is returned. Also, if \c in_memory is configured for the database and the insert requires more than the configured cache size to complete, ::WT_CACHE_FULL is returned.

modify: Option<unsafe extern "C" fn(*mut __wt_cursor, *mut __wt_modify, i32) -> i32>

Modify an existing record.

Both the key and value must be set and the record must already exist; the record will be updated.

Modifications are specified in WT_MODIFY structures. Modifications are applied in order and later modifications can update earlier ones.

The modify method is only supported on strings (value format type \c S), or raw byte arrays accessed using a WT_ITEM structure (value format type \c u).

Calling the WT_CURSOR::modify method outside of snapshot isolation can lead to unexpected results. While \c read-committed isolation is supported with the WT_CURSOR::modify method, \c read-uncommitted isolation is not.

@snippet ex_all.c Modify an existing record

On success, the cursor ends positioned at the modified record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the cursor no longer needs that position.

The maximum length of a single column stored in a table is not fixed (as it partially depends on the underlying file configuration), but is always a small number of bytes less than 4GB.

The WT_CURSOR::modify method stores a change record in cache and writes a change record to the log, instead of the usual complete value. This can reduce cache and logging requirements, but may result in slower reads because the complete value must be assembled during retrieval.

@param cursor the cursor handle @param entries an array of modification data structures @param nentries the number of modification data structures @errors In particular, if \c in_memory is configured for the database and the modify requires more than the configured cache size to complete, ::WT_CACHE_FULL is returned.

update: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Update an existing record and optionally insert a record.

If the cursor was configured with “overwrite=true” (the default), both the key and value must be set; if the record already exists, the key’s value will be updated, otherwise, the record will be inserted.

@snippet ex_all.c Update an existing record or insert a new record

If the cursor was not configured with “overwrite=true”, both the key and value must be set and the record must already exist; the record will be updated.

@snippet ex_all.c Update an existing record and fail if DNE

On success, the cursor ends positioned at the modified record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the cursor no longer needs that position. (The WT_CURSOR::insert method never keeps a cursor position and may be more efficient for that reason.)

The maximum length of a single column stored in a table is not fixed (as it partially depends on the underlying file configuration), but is always a small number of bytes less than 4GB.

@param cursor the cursor handle @errors In particular, if \c overwrite=false is configured and no record with the specified key exists, ::WT_NOTFOUND is returned. Also, if \c in_memory is configured for the database and the update requires more than the configured cache size to complete, ::WT_CACHE_FULL is returned.

remove: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Remove a record.

If the cursor was configured with “overwrite=true” (the default), the key must be set; the key’s record will be removed if it exists, no error will be returned if the record does not exist.

@snippet ex_all.c Remove a record

If the cursor was configured with “overwrite=false” (not the default), the key must be set and the key’s record must exist; the record will be removed.

Any cursor position does not change: if the cursor was positioned before the WT_CURSOR::remove call, the cursor remains positioned at the removed record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the cursor no longer needs that position. If the cursor was not positioned before the WT_CURSOR::remove call, the cursor ends with no position, and a subsequent call to the WT_CURSOR::next (WT_CURSOR::prev) method will iterate from the beginning (end) of the table.

@snippet ex_all.c Remove a record and fail if DNE

Removing a record in a fixed-length bit field column-store (that is, a store with an ‘r’ type key and ‘t’ type value) is identical to setting the record’s value to 0.

@param cursor the cursor handle @errors In particular, if \c overwrite=false is configured and no record with the specified key exists, ::WT_NOTFOUND is returned.

reserve: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Reserve an existing record so a subsequent write is less likely to fail due to a conflict between concurrent operations.

The key must first be set and the record must already exist.

@snippet ex_all.c Reserve a record

On success, the cursor ends positioned at the specified record; to minimize cursor resources, the WT_CURSOR::reset method should be called as soon as the cursor no longer needs that position.

@param cursor the cursor handle @errors

close: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

Close the cursor.

This releases the resources associated with the cursor handle. Cursors are closed implicitly by ending the enclosing connection or closing the session in which they were opened.

@snippet ex_all.c Close the cursor

@param cursor the cursor handle @errors

reconfigure: Option<unsafe extern "C" fn(*mut __wt_cursor, *const i8) -> i32>

Reconfigure the cursor.

The cursor is reset.

@snippet ex_all.c Reconfigure a cursor

@param cursor the cursor handle @configstart{WT_CURSOR.reconfigure, see dist/api_data.py} @config{append, append the value as a new record, creating a new record number key; valid only for cursors with record number keys., a boolean flag; default \c false.} @config{overwrite, configures whether the cursor’s insert, update and remove methods check the existing state of the record. If \c overwrite is \c false, WT_CURSOR::insert fails with ::WT_DUPLICATE_KEY if the record exists, WT_CURSOR::update and WT_CURSOR::remove fail with ::WT_NOTFOUND if the record does not exist., a boolean flag; default \c true.} @configend @errors

cache: Option<unsafe extern "C" fn(*mut __wt_cursor) -> i32>

reopen: Option<unsafe extern "C" fn(*mut __wt_cursor, bool) -> i32>

uri_hash: u64

q: __wt_cursor__bindgen_ty_1

recno: u64

raw_recno_buf: [u8; 9]

json_private: *mut c_void

lang_private: *mut c_void

key: __wt_item

value: __wt_item

saved_err: i32

internal_uri: *const i8

flags: u32