Class Fetcher.

The Fetcher class retrieves Message data for some/all messages in a Mailbox. It's a management class to do Message and Mailbox aspects of the job; internal classes provide the Query or PreparedStatement objects necessary to fetch specific data.

A Fetcher lives for a while, fetching data about a range of messages. Whenever it finishes its current retrieval, it finds the largest range of messages currently needing retrieval, and issues an SQL select for them. Typically the select ends with "mailbox=$71 and uid in any($72). When the Fetcher isn't useful any more, its owner drops it on the floor.

Fetcher::Fetcher( List<Message> * messages, EventHandler * e, Buffer * buffer )

Constructs an empty Fetcher which will fetch messages and notify e when it's done, taking care to keep buffer short.

Fetcher::Fetcher( Message * m, EventHandler * owner )

Constructs a Fetcher which will fetch the single message m by Message::databaseId() and notify owner when it's done.

The constructed Fetcher can only fetch bodies, headers and addresses.

void Fetcher::addMessage( Message * message )

Adds message to the list of messages fetched. This does not re-execute the fetcher - the user must execute() it if done().

void Fetcher::addMessages( List<Message> * messages )

Adds messages to the list of messages fetched. This does not re-execute the fetcher - the user must execute() it if done().

void Fetcher::bindIds( Query * query, uint n, Type type )

Finds out which messages need information of type, and binds a list of their database IDs to parameter n of query.

bool Fetcher::done() const

Returns true if this Fetcher has finished the work assigned to it (and will perform no further message updates), and false if it is still working.

void Fetcher::fetch( Type t )

Instructs this Fetcher to fetch data of type t.

bool Fetcher::fetching( Type t ) const

Returns true if this Fetcher will fetch (or is fetching) data of type t. Returns false until fetch() has been called for t.

void Fetcher::makeQueries()

Issues the necessary selects to retrieve data and feed the decoders. This function does some optimisation of the generated SQL.

void Fetcher::prepareBatch()

Messages are fetched in batches, so that we can deliver some rows early on. This function adjusts the size of the batches so we'll get about one batch every 6 seconds, and updates the tables so we have a batch ready for reading.

void Fetcher::setTransaction( Transaction * t )

Records that all queries done by this Fetcher should be performed within t. This can be useful e.g. if some messages may be locked by t, or if the retrieval is tied to t logically.

void Fetcher::start()

Decides whether to issue a number of parallel SQL selects or to use a two-stage process with a complex intermediate data structure. The decision is based on entirely heuristic factors.

This function knows something about how many messages we want, but it doesn't know how many we'll get. The two numbers are equal in practice.

void Fetcher::submit( Query * q )

This internal helper makes sure q is executed by the database.

void Fetcher::waitForEnd()

Checks whether all queries and decoders are done. When the decoders are, then the Fetcher may or may not be. Perhaps it's time to start another batch, perhaps it's time to notify the owner.