PCursor Class Reference

Persistent cursor wrapper around btr_pcur_t. More...

Public Member Functions
	PCursor (btr_pcur_t *pcur, mtr_t *mtr, size_t read_level)
	Constructor. More...
void	save_current_user_record_as_last_processed () noexcept
	Store the position of the user record that is added to the key buffer and, commit the mini-transaction. More...
void	restore_to_last_processed_user_record () noexcept
	Restore the cursor to the saved record. More...
void	save_previous_user_record_as_last_processed () noexcept
	This method must be called after all records on a page are processed and cursor is positioned at supremum. More...
void	restore_to_first_unprocessed () noexcept
	Restore the cursor to the record which comes next after the saved position by the paired method save_previous_user_record_as_last_processed(). More...
dberr_t	move_to_next_block (dict_index_t *index)
	Move to the next block. More...
bool	restore_to_largest_le_position_saved () noexcept
	Restore the cursor to the saved record. More...
page_cur_t *	get_page_cursor () noexcept
bool	is_after_last_on_page () const noexcept
size_t	read_level () const noexcept

Private Member Functions
void	save_level_one_progress () noexcept
	This method must be called when cursor is positioned at supremum of the page at the level one of the index. More...
dberr_t	restore_level_one_progress () noexcept
	This method must be called to restore to the record on the non-leaf page (level one) of the index. More...
dberr_t	move_to_next_block_at_leaf_level (dict_index_t *index)
	Move to the next block at the leaf level of the index. More...
dberr_t	move_to_next_block_at_level_one (dict_index_t *index)
	Move to the next block at the level one of the index. More...
dberr_t	move_to_user_rec_on_next_page () noexcept
	Move to the first user record on the next page. More...

Private Attributes
mtr_t *	m_mtr {}
	Mini-transaction. More...
btr_pcur_t *	m_pcur {}
	Persistent cursor. More...
size_t	m_read_level {}
	Level where the cursor is positioned or need to be positioned in case of restore. More...

Detailed Description

Persistent cursor wrapper around btr_pcur_t.

Constructor & Destructor Documentation

PCursor()

PCursor::PCursor ( btr_pcur_t *  pcur, mtr_t *  mtr, size_t  read_level  )

inline

Constructor.

Parameters

[in,out]	pcur	Persistent cursor in use.
[in]	mtr	Mini-transaction used by the persistent cursor.
[in]	read_level	Read level where the block should be present.

Member Function Documentation

get_page_cursor()

page_cur_t * PCursor::get_page_cursor ( )

inlinenoexcept

Returns

the current page cursor.

is_after_last_on_page()

bool PCursor::is_after_last_on_page ( ) const

inlinenoexcept

Returns

true if cursor is after last on page.

move_to_next_block()

dberr_t PCursor::move_to_next_block

(

dict_index_t *

index

)

Move to the next block.

Parameters

[in]

index

Index being traversed.

Returns

DB_SUCCESS or error code.

move_to_next_block_at_leaf_level()

dberr_t PCursor::move_to_next_block_at_leaf_level ( dict_index_t *  index )

private

Move to the next block at the leaf level of the index.

If other thread(s) are waiting to acquire the latches on the index then first save the last processed user record, pause, give chance to the other threads to execute, then restore the cursor to next unprocessed record, which typically is the first record on next page, if the tree was not modified meanwhile.

Parameters

[in]

index

Index being traversed.

Returns

DB_SUCCESS or error code.

move_to_next_block_at_level_one()

dberr_t PCursor::move_to_next_block_at_level_one ( dict_index_t *  index )

private

Move to the next block at the level one of the index.

If other thread(s) are waiting to acquire the latches on the index then first pause, give chance the other threads to execute, then restore the cursor before positioning it to user record on next page. The latch on next page is acquired without waiting in a retry loop, otherwise waiting might cause deadlock with other tree modifying operations.

Parameters

[in]

index

Index being traversed.

Returns

DB_SUCCESS or error code.

move_to_user_rec_on_next_page()

dberr_t PCursor::move_to_user_rec_on_next_page ( )

privatenoexcept

Move to the first user record on the next page.

Release the latches on the current page and obtain the S-latch on next page. If it is non-leaf level then S-latch is obtained in the optimistic/non-blocking way, which can fail with DB_LOCK_WAIT. Caller must add the retry logic to handle this error code.

Returns

DB_SUCCESS or error code.

read_level()

size_t PCursor::read_level ( ) const

inlinenoexcept

Returns

Level where the cursor is intended.

restore_level_one_progress()

dberr_t PCursor::restore_level_one_progress ( )

privatenoexcept

This method must be called to restore to the record on the non-leaf page (level one) of the index.

It must be paired with save_level_one_progress(). If the cursor was saved to the record <min-key value, child_page_no> position, then the restored cursor is positioned to the <min-key value+, child_page_no^>. The min-key value+ is the value that comes next after the saved value min-key value. As PAGE_CUR_G mode is not supported for level 1, this function searches for such a record in two steps:

1. using PAGE_CUR_LE it finds a record which is lower-or-equal min_key value
2. adjusts the position by moving one record forward The later step might require moving to the next page, and this function tries to latch the next page without any other thread waiting to latch it. If the latch could not be obtained on the page, then the method returns the DB_LOCK_NOWAIT error code. The caller must implement retry logic to handle this error code.

   Returns

   DB_SUCCESS or error code.

restore_to_first_unprocessed()

void PCursor::restore_to_first_unprocessed ( )

noexcept

Restore the cursor to the record which comes next after the saved position by the paired method save_previous_user_record_as_last_processed().

If there is no such record, it will restore to supremum on the last leaf page.

Note

This method must be paired with save_previous_user_record_as_last_processed() to save the record position

restore_to_largest_le_position_saved()

bool PCursor::restore_to_largest_le_position_saved ( )

noexcept

Restore the cursor to the saved record.

If the saved record was physically removed, then restore to the largest record which is smaller than the saved record.

Returns

true if restored to the same record, false otherwise

restore_to_last_processed_user_record()

void PCursor::restore_to_last_processed_user_record ( )

noexcept

Restore the cursor to the saved record.

If the saved record was physically removed then restore to the largest record which is smaller than the saved record. If all records were removed then restore the cursor to the infimum; this must be fine if the next step of the caller is to advance the cursor.

Note

This method must be paired with save_current_user_record_as_last_processed() to save the record position

save_current_user_record_as_last_processed()

void PCursor::save_current_user_record_as_last_processed ( )

noexcept

Store the position of the user record that is added to the key buffer and, commit the mini-transaction.

The cursor must not be positioned at infimum or supremum.

Note

This method must be paired with restore_to_last_processed_user_record() to restore the record position

save_level_one_progress()

void PCursor::save_level_one_progress ( )

privatenoexcept

This method must be called when cursor is positioned at supremum of the page at the level one of the index.

It saves the min-key value of the last leaf page referenced on the page. This method must be paired with restore_level_one_progress() to restore cursor to a record on the non-leaf page which points to the next leaf page to process.

See also

restore_level_one_progress for details.

save_previous_user_record_as_last_processed()

void PCursor::save_previous_user_record_as_last_processed ( )

noexcept

This method must be called after all records on a page are processed and cursor is positioned at supremum.

Under this assumption, it stores the position BTR_PCUR_AFTER the last user record on the page. This method must be paired with restore_to_first_unprocessed() to restore to a record which comes right after the value of the stored last processed record

See also

restore_to_first_unprocessed for details.

Member Data Documentation

m_mtr

mtr_t* PCursor::m_mtr {}

private

Mini-transaction.

m_pcur

btr_pcur_t* PCursor::m_pcur {}

private

Persistent cursor.

m_read_level

size_t PCursor::m_read_level {}

private

Level where the cursor is positioned or need to be positioned in case of restore.

---

The documentation for this class was generated from the following file:

• storage/innobase/row/row0pread.cc