Struct CursorImpl 

pub struct CursorImpl { /* private fields */ }

The internal implementation of a database cursor.

A CursorImpl tracks a position in a database and provides get/put/delete operations. The cursor state machine ensures proper initialization before operations.

a cursor tracks its position via a BIN reference and slot index. This implementation wires cursor traversal to noxu_tree::Tree:

• get_first / get_last — use Tree::get_first_node() / Tree::get_last_node().
• retrieve_next — increments current_index within the BIN and, when the BIN is exhausted, calls Tree::get_next_bin() / Tree::get_prev_bin() to cross BIN boundaries CursorImpl.getNext()).
• search — uses Tree::search() to locate the exact key.
• put / delete — mutate the tree in-place using Tree::insert() / Tree::delete().

(4096 lines in 7.5.11).

Implementations

impl CursorImpl

pub fn new(db_impl: Arc<RwLock<DatabaseImpl>>, locker_id: i64) -> Self

Creates a new CursorImpl for the given database.

The cursor is initially in the NotInitialized state and must be positioned via a search operation before get/put/delete operations can be performed.

Arguments

• db_impl - The database implementation this cursor operates on
• locker_id - The locker (transaction) ID for this cursor

pub fn with_log_manager( db_impl: Arc<RwLock<DatabaseImpl>>, locker_id: i64, log_manager: Arc<LogManager>, ) -> Self

Creates a new CursorImpl wired to a WAL.

Write operations (put, delete) will record LnLogEntry entries in the provided LogManager before mutating the in-memory tree.

pub fn with_env_invalid(self, flag: Arc<AtomicBool>) -> Self

Wires the environment-invalidity flag for hot-path validity checks.

Stores a clone of EnvironmentImpl::is_invalid_flag() so that check_state() can detect a failed environment on every cursor operation without acquiring the environment lock. X-13 fix.

pub fn with_lock_manager(self, lock_manager: Arc<LockManager>) -> Self

Wires a lock manager for per-record locking.

CursorImpl receiving a Locker from DatabaseImpl.openCursor(). Returns self for builder-style chaining.

pub fn with_txn(self, txn: Arc<Mutex<Txn>>) -> Self

Wires an explicit transaction for write-lock tracking.

When set, write operations (put, delete) acquire WRITE locks via the Txn and record abort before-images in WriteLockInfo, enabling transaction rollback.

Being constructed with a Txn locker. Returns self for builder-style chaining.

pub fn attach_txn(&mut self, txn: Arc<Mutex<Txn>>)

Setter equivalent of Self::with_txn for callers that need to attach a Txn to an already-built cursor (e.g. Database::with_auto_txn which constructs the cursor first, then wires the synthetic auto-txn).

pub fn get_id(&self) -> i64

Returns the unique cursor ID.

Used for debugging and cursor tracking.

pub fn get_database(&self) -> &Arc<RwLock<DatabaseImpl>>

Returns the database this cursor operates on.

pub fn get_locker_id(&self) -> i64

Returns the locker ID.

pub fn is_initialized(&self) -> bool

Returns true if the cursor is initialized (positioned on a record).

pub fn is_closed(&self) -> bool

Returns true if the cursor is closed.

pub fn get_current_key(&self) -> Option<&[u8]>

Returns the current key, if positioned.

pub fn get_current_data(&self) -> Option<&[u8]>

Returns the current data, if positioned.

pub fn get_current_lsn(&self) -> u64

Returns the current LSN, if positioned.

pub fn search( &mut self, key: &[u8], data: Option<&[u8]>, search_mode: SearchMode, ) -> Result<OperationStatus, DbiError>

Positions the cursor at a specific key.

/ CursorImpl.searchRange().

Uses Tree::search(key) to locate the BIN slot for the key:

• SearchMode::Set / SearchMode::Both — exact key match required. Returns NotFound if the key is not present.
• SearchMode::SetRange / SearchMode::BothRange — positions at the first key >= the search key (range search). Currently degrades to an exact-match check; full range support requires iterating forward until the key is >= the search key.

Arguments

• key - The key to search for
• data - Optional data for Both/BothRange modes
• search_mode - The search mode (Set, Both, SetRange, BothRange)

Returns

• Success if the key was found and cursor positioned
• NotFound if the key does not exist

pub fn get_first(&mut self) -> Result<OperationStatus, DbiError>

Positions the cursor at the first (smallest) record in the database.

.

Uses Tree::get_first_node() to descend to the leftmost BIN, then positions the cursor at slot 0.

Returns

• Success if the tree is non-empty
• NotFound if the tree is empty

pub fn get_last(&mut self) -> Result<OperationStatus, DbiError>

Positions the cursor at the last (largest) record in the database.

.

Uses Tree::get_last_node() to descend to the rightmost BIN, then positions the cursor at the last slot.

Returns

• Success if the tree is non-empty
• NotFound if the tree is empty

pub fn get_current(&self) -> Result<(Vec<u8>, Vec<u8>), DbiError>

Retrieves the current record.

Returns the key and data at the cursor’s current position.

Returns

A tuple of (key, data) for the current record.

Errors

• CursorNotInitialized if the cursor is not positioned on a record
• CursorClosed if the cursor has been closed

pub fn is_current_slot_deleted(&self) -> bool

Returns true if the slot the cursor is positioned on has been deleted since the cursor was last positioned.

: analogous to checking KNOWN_DELETED_BIT / entry removal on Cursor.getCurrentLN() path — returns KEYEMPTY when the record is gone.

pub fn retrieve_next( &mut self, mode: GetMode, ) -> Result<OperationStatus, DbiError>

Moves the cursor to the next/previous record.

.

Advances current_index within the current BIN. When the BIN is exhausted (forward: index >= nEntries; backward: index < 0) the cursor moves to the adjacent BIN via Tree::get_next_bin() / Tree::get_prev_bin(), mirroring call to tree.getNextBin(anchorBIN) / tree.getPrevBin(anchorBIN).

The GetMode parameter controls direction and duplicate handling:

• Next / NextNoDup / NextDup — move forward
• Prev / PrevNoDup / PrevDup — move backward

Returns

• Success if positioned on a new record
• NotFound if there are no more records in that direction

pub fn put( &mut self, key: &[u8], data: &[u8], put_mode: PutMode, ) -> Result<OperationStatus, DbiError>

Inserts or updates a record at the cursor position.

Write path:

1. Checks state and, for Current mode, that the cursor is initialized.
2. For NoOverwrite: searches the tree; returns KeyExist if found.
3. Calls Tree::insert(key, data, lsn) to insert/update in the BIN.
4. Updates the cursor position to the newly written record.

Note: locking (step 2 in the) and WAL logging (step 3 in the) are not yet wired here — they require LogManager integration (P0 gap).

Arguments

• key - The key to insert/update
• data - The data value
• put_mode - The insertion mode

Returns

• Success if the record was inserted/updated
• KeyExist if NoOverwrite mode and key already exists

pub fn delete(&mut self) -> Result<OperationStatus, DbiError>

Deletes the record at the cursor position.

Delete path:

1. Checks that the cursor is initialized.
2. Writes a DeleteLN log entry to the WAL (if log manager is present).
3. Calls Tree::delete(key) to remove the entry from the BIN.
4. Resets cursor to NotInitialized (matching behaviour).

Returns

• Success if the record was deleted

Errors

• CursorNotInitialized if cursor is not positioned
• CursorClosed if cursor has been closed

pub fn count(&self) -> Result<i64, DbiError>

Counts the number of duplicates at the current key position.

For sorted-dup databases, traverses all records sharing the same primary key. For non-dup databases, returns 1 if positioned.

7.5.

Returns

The count of duplicate records at the current key.

Errors

• CursorNotInitialized if cursor is not positioned
• CursorClosed if cursor has been closed

pub fn dup(&self, same_position: bool) -> Result<CursorImpl, DbiError>

Creates a duplicate of this cursor at the same position.

If same_position is true, the new cursor is positioned at the same record as this cursor. Otherwise, the new cursor is created in the NotInitialized state.

The duplicated cursor shares the same locker (transaction) as the original cursor.

Arguments

• same_position - Whether to copy the current position

Returns

A new CursorImpl with the same or uninitialized position.

Errors

• CursorClosed if the cursor has been closed

pub fn close(&mut self) -> Result<(), DbiError>

first close.

Returns

always (never fails).

Trait Implementations

impl Drop for CursorImpl

fn drop(&mut self)

Ensures the cursor is closed when dropped.

This provides automatic cleanup if the user forgets to explicitly close the cursor. Note that it’s still better practice to call close() explicitly to handle potential errors.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.