Storage Engine API
Public Types | Public Member Functions | List of all members
mongo::SortedDataInterface::Cursor Class Referenceabstract

Navigates over the sorted data. More...

#include <sorted_data_interface.h>

Detailed Description

Navigates over the sorted data.

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

  • The direction that next() moves.
  • If a seek method hits an exact match on key, forward cursors will be positioned on the first value for that key, reverse cursors on the last.
  • If a seek method or restore does not hit an exact match, cursors will be positioned on the closest position after the query in the direction of the search.
  • The end position is on the "far" side of the query. In a forward cursor that means that it is the lowest value for the key if the end is exclusive or the first entry past the key if the end is inclusive or there are no exact matches.

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 the save methods may throw WriteConflict exception. 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). All methods only provide the basic guarantee for exceptions other than WCE.

Any returned unowned BSON is only valid until the next call to any method on this interface. The implementations must assume that passed-in unowned BSON is only valid for the duration of the call.

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

Public Types

enum  RequestedInfo { kJustExistance = 0, kWantKey = 1, kWantLoc = 2, kKeyAndLoc = kWantKey | kWantLoc }
 Tells methods that return an IndexKeyEntry what part of the data the caller is interested in. More...
 

Public Member Functions

virtual ~Cursor ()=default
 
virtual void setEndPosition (const BSONObj &key, bool inclusive)=0
 Sets the position to stop scanning. More...
 
virtual boost::optional< IndexKeyEntry > next (RequestedInfo parts=kKeyAndLoc)=0
 Moves forward and returns the new data or boost::none if there is no more data. More...
 
virtual boost::optional< IndexKeyEntry > seek (const BSONObj &key, bool inclusive, RequestedInfo parts=kKeyAndLoc)=0
 Seeks to the provided key and returns current position. More...
 
virtual boost::optional< IndexKeyEntry > seek (const IndexSeekPoint &seekPoint, RequestedInfo parts=kKeyAndLoc)=0
 Seeks to the position described by seekPoint and returns the current position. More...
 
virtual boost::optional< IndexKeyEntry > seekExact (const BSONObj &key, RequestedInfo parts=kKeyAndLoc)
 Seeks to a key with a hint to the implementation that you only want exact matches. 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 void saveUnpositioned ()
 Prepares for state changes in underlying data without necessarily saving the current state. More...
 
virtual void 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...
 

Member Enumeration Documentation

◆ RequestedInfo

enum mongo::SortedDataInterface::Cursor::RequestedInfo

Tells methods that return an IndexKeyEntry what part of the data the caller is interested in.

Methods returning an engaged optional<T> will only return null RecordIds or empty BSONObjs if they have been explicitly left out of the request.

Implementations are allowed to return more data than requested, but not less.

Enumerator
kJustExistance 
kWantKey 
kWantLoc 
kKeyAndLoc 

Constructor & Destructor Documentation

◆ ~Cursor()

virtual mongo::SortedDataInterface::Cursor::~Cursor ( )
virtualdefault

Member Function Documentation

◆ detachFromOperationContext()

virtual void mongo::SortedDataInterface::Cursor::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.

◆ next()

virtual boost::optional<IndexKeyEntry> mongo::SortedDataInterface::Cursor::next ( RequestedInfo  parts = kKeyAndLoc)
pure virtual

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

If not positioned, returns boost::none.

◆ reattachToOperationContext()

virtual void mongo::SortedDataInterface::Cursor::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.

◆ restore()

virtual void mongo::SortedDataInterface::Cursor::restore ( )
pure virtual

Recovers from potential state changes in underlying data.

If the former position no longer exists, a 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 saveUnpositioned().

◆ save()

virtual void mongo::SortedDataInterface::Cursor::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.

◆ saveUnpositioned()

virtual void mongo::SortedDataInterface::Cursor::saveUnpositioned ( )
inlinevirtual

Prepares for state changes in underlying data without necessarily saving the current state.

The cursor's position when restored is unspecified. Caller is expected to seek following the restore.

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

◆ seek() [1/2]

virtual boost::optional<IndexKeyEntry> mongo::SortedDataInterface::Cursor::seek ( const BSONObj &  key,
bool  inclusive,
RequestedInfo  parts = kKeyAndLoc 
)
pure virtual

Seeks to the provided key and returns current position.

TODO consider removing once IndexSeekPoint has been cleaned up a bit. In particular, need a way to specify use whole keyPrefix and nothing else and to support the combination of empty and exclusive. Should also make it easier to construct for the common cases.

◆ seek() [2/2]

virtual boost::optional<IndexKeyEntry> mongo::SortedDataInterface::Cursor::seek ( const IndexSeekPoint &  seekPoint,
RequestedInfo  parts = kKeyAndLoc 
)
pure virtual

Seeks to the position described by seekPoint and returns the current position.

NOTE: most implementations should just pass seekPoint to IndexEntryComparison::makeQueryObject().

◆ seekExact()

virtual boost::optional<IndexKeyEntry> mongo::SortedDataInterface::Cursor::seekExact ( const BSONObj &  key,
RequestedInfo  parts = kKeyAndLoc 
)
inlinevirtual

Seeks to a key with a hint to the implementation that you only want exact matches.

If an exact match can't be found, boost::none will be returned and the resulting position of the cursor is unspecified.

◆ setEndPosition()

virtual void mongo::SortedDataInterface::Cursor::setEndPosition ( const BSONObj &  key,
bool  inclusive 
)
pure virtual

Sets the position to stop scanning.

An empty key unsets the end position.

If next() hits this position, or a seek method attempts to seek past it they unposition the cursor and return boost::none.

Setting the end position should be done before seeking since the current position, if any, isn't checked.

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