mongo::RecordCursor Class Reference

Retrieves Records from a RecordStore. More...

#include <record_store.h>

Inheritance diagram for mongo::RecordCursor:

Detailed Description

Retrieves Records from a RecordStore.

A cursor is constructed with a direction flag with the following effects:

• The direction that next() moves.
• If a restore cannot return to the saved position, cursors will be positioned on the closest position after the query in the direction of the scan.

A cursor is tied to a transaction, such as the OperationContext or a WriteUnitOfWork inside that context. Any cursor acquired inside a transaction is invalid outside of that transaction, instead use the save and restore methods to reestablish the cursor.

Any method other than invalidate and the save methods may throw WriteConflictException. If that happens, the cursor may not be used again until it has been saved and successfully restored. If next() or restore() throw a WCE the cursor's position will be the same as before the call (strong exception guarantee). All other methods leave the cursor in a valid state but with an unspecified position (basic exception guarantee). If any exception other than WCE is thrown, the cursor must be destroyed, which is guaranteed not to leak any resources.

Any returned unowned BSON is only valid until the next call to any method on this interface.

Implementations may override any default implementation if they can provide a more efficient implementation.

Storage engines only need to implement the derived SeekableRecordCursor, but may choose to implement this simpler interface for cursors used for repair or random traversal.

IMPORTANT NOTE FOR DOCUMENT-LOCKING ENGINES: If you implement capped collections with a "visibility" system such that documents that exist in your snapshot but were inserted after the last uncommitted document are hidden, you must follow the following rules:

• next() on forward cursors must never return invisible documents.
• If next() on a forward cursor hits an invisible document, it should behave as if it hit the end of the collection.
• Reverse cursors must ignore the visibility filter. That means that they initially return the newest committed record in the collection and may skip over uncommitted records.
• SeekableRecordCursor::seekExact() must ignore the visibility filter and return the requested document even if it is supposed to be invisible. TODO SERVER-18934 Handle this above the storage engine layer so storage engines don't have to deal with capped visibility.

Public Member Functions
virtual	~RecordCursor ()=default
virtual boost::optional< Record >	next ()=0
	Moves forward and returns the new data or boost::none if there is no more data. More...
virtual void	save ()=0
	Prepares for state changes in underlying data in a way that allows the cursor's current position to be restored. More...
virtual bool	restore ()=0
	Recovers from potential state changes in underlying data. More...
virtual void	detachFromOperationContext ()=0
	Detaches from the OperationContext and releases any storage-engine state. More...
virtual void	reattachToOperationContext (OperationContext *opCtx)=0
	Reattaches to the OperationContext and reacquires any storage-engine state. More...
virtual void	invalidate (OperationContext *opCtx, const RecordId &id)
	Inform the cursor that this id is being invalidated. More...
virtual std::unique_ptr< RecordFetcher >	fetcherForNext () const
	Returns a RecordFetcher if needed for a call to next() or none if unneeded. More...

Constructor & Destructor Documentation

~RecordCursor()

virtual mongo::RecordCursor::~RecordCursor ( )

virtualdefault

Member Function Documentation

detachFromOperationContext()

virtual void mongo::RecordCursor::detachFromOperationContext ( )

pure virtual

Detaches from the OperationContext and releases any storage-engine state.

It is only legal to call this when in a "saved" state. While in the "detached" state, it is only legal to call reattachToOperationContext or the destructor. It is not legal to call detachFromOperationContext() while already in the detached state.

Implemented in mongo::WiredTigerRecordStore::RandomCursor, mongo::WiredTigerRecordStoreCursorBase, mongo::RecordStoreV1Base::IntraExtentIterator, mongo::EphemeralForTestRecordStore::ReverseCursor, mongo::EphemeralForTestRecordStore::Cursor, mongo::MobileRecordStore::Cursor, mongo::EmptyRecordCursor, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, and mongo::RecordStoreV1RepairCursor.

fetcherForNext()

virtual std::unique_ptr<RecordFetcher> mongo::RecordCursor::fetcherForNext ( ) const

inlinevirtual

Returns a RecordFetcher if needed for a call to next() or none if unneeded.

Reimplemented in mongo::RecordStoreV1Base::IntraExtentIterator, mongo::CappedRecordStoreV1Iterator, and mongo::SimpleRecordStoreV1Iterator.

invalidate()

virtual void mongo::RecordCursor::invalidate ( OperationContext *  opCtx, const RecordId &  id  )

inlinevirtual

Inform the cursor that this id is being invalidated.

Must be called between save and restore. The opCtx is that of the operation causing the invalidation, not the opCtx using the cursor.

WARNING: Storage engines other than MMAPv1 should use the default implementation, and not depend on this being called.

Reimplemented in mongo::RecordStoreV1Base::IntraExtentIterator, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, and mongo::RecordStoreV1RepairCursor.

next()

virtual boost::optional<Record> mongo::RecordCursor::next ( )

pure virtual

Moves forward and returns the new data or boost::none if there is no more data.

Continues returning boost::none once it reaches EOF.

Implemented in mongo::WiredTigerRecordStore::RandomCursor, mongo::WiredTigerRecordStoreCursorBase, mongo::RecordStoreV1Base::IntraExtentIterator, mongo::EphemeralForTestRecordStore::ReverseCursor, mongo::EphemeralForTestRecordStore::Cursor, mongo::MobileRecordStore::Cursor, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, mongo::RecordStoreV1RepairCursor, and mongo::EmptyRecordCursor.

reattachToOperationContext()

virtual void mongo::RecordCursor::reattachToOperationContext ( OperationContext *  opCtx )

pure virtual

Reattaches to the OperationContext and reacquires any storage-engine state.

It is only legal to call this in the "detached" state. On return, the cursor is left in a "saved" state, so callers must still call restoreState to use this object.

Implemented in mongo::WiredTigerRecordStore::RandomCursor, mongo::WiredTigerRecordStoreCursorBase, mongo::RecordStoreV1Base::IntraExtentIterator, mongo::EphemeralForTestRecordStore::ReverseCursor, mongo::EphemeralForTestRecordStore::Cursor, mongo::MobileRecordStore::Cursor, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, mongo::RecordStoreV1RepairCursor, and mongo::EmptyRecordCursor.

restore()

virtual bool mongo::RecordCursor::restore ( )

pure virtual

Recovers from potential state changes in underlying data.

Returns false if it is invalid to continue using this iterator. This usually means that capped deletes have caught up to the position of this iterator and continuing could result in missed data.

If the former position no longer exists, but it is safe to continue iterating, the following call to next() will return the next closest position in the direction of the scan, if any.

This handles restoring after either save() or SeekableRecordCursor::saveUnpositioned().

Implemented in mongo::WiredTigerRecordStore::RandomCursor, mongo::WiredTigerRecordStoreCursorBase, mongo::RecordStoreV1Base::IntraExtentIterator, mongo::EphemeralForTestRecordStore::ReverseCursor, mongo::EphemeralForTestRecordStore::Cursor, mongo::MobileRecordStore::Cursor, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, mongo::EmptyRecordCursor, and mongo::RecordStoreV1RepairCursor.

save()

virtual void mongo::RecordCursor::save ( )

pure virtual

Prepares for state changes in underlying data in a way that allows the cursor's current position to be restored.

It is safe to call save multiple times in a row. No other method (excluding destructor) may be called until successfully restored.

Implemented in mongo::WiredTigerRecordStore::RandomCursor, mongo::WiredTigerRecordStoreCursorBase, mongo::RecordStoreV1Base::IntraExtentIterator, mongo::EphemeralForTestRecordStore::ReverseCursor, mongo::EphemeralForTestRecordStore::Cursor, mongo::MobileRecordStore::Cursor, mongo::CappedRecordStoreV1Iterator, mongo::SimpleRecordStoreV1Iterator, mongo::EmptyRecordCursor, and mongo::RecordStoreV1RepairCursor.

---

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

• /home/louis/git/mongodbsource.github.io/src/src/mongo/db/storage/record_store.h