Cursor Class Reference

#include <Pt/Db/Cursor.h>

Batch cursor for large query results. More...

Public Member Functions
	Cursor ()
	Creates a closed cursor.
	Cursor (ICursor *cursor, size_type batchSize)
	Takes ownership of cursor with a fixed batchSize.
bool	fetch ()
	Fetches the next batch synchronously.
Result &	result ()
	Returns the current batch buffer.
const Result &	result () const
	Returns the current batch buffer.
Signal &	fetchFinished ()
	Signal emitted when an asynchronous batch is ready.
bool	isOpen () const
	Returns true if the cursor is open.
void	beginFetch ()
	Starts asynchronous retrieval of the next batch.
Result &	endFetch ()
	Completes an asynchronous fetch.
ICursor *	impl ()
	Returns the backend cursor.
const ICursor *	impl () const
	Returns the backend cursor.
void	close ()
	Closes the cursor and releases its resources.
Iterator	begin ()
	Returns an iterator to the first row, fetching the first batch.
Iterator	end ()
	Returns the end sentinel iterator.

Detailed Description

Cursor is the batch reader the group described. Obtain it from Statement::getCursor() with the number of rows per batch. It is a shared value. The backend cursor is closed when the last copy is destroyed or when close() is called. A default-constructed cursor is closed.

Range-for walks every row and fetches the next batch when the current one is exhausted. That path is synchronous. begin() fetches the first batch; end() is the sentinel.

fetch() loads the next batch into the cursor's buffer and returns true while the batch is not empty. result() is that buffer, a Result of the current batch only.

Asynchronous fetch needs a connection attached with setActive(). Connect to fetchFinished(), then call beginFetch(). In the slot, endFetch() returns the batch. isOpen() is true while the cursor can still produce rows. Call beginFetch() again for the next batch while it stays open. close() cancels a fetch in progress.

Do not run another operation on the same connection until the cursor is closed.

for(const Pt::Db::Row& row : stmt.getCursor(100))
    process(row);

Member Function Documentation

fetch()

bool fetch

(

)

Returns

True if the batch is not empty.

endFetch()

Result & endFetch

(

)

Returns an empty result when no more rows are available; the cursor is closed in that case.