apt @VERSION@
Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Friends

pkgAcquire Class Reference

The core download scheduler. {{{. More...

#include <acquire.h>

List of all members.

Classes

class  Item
 Represents the process by which a pkgAcquire object should {{{ retrieve a file or a collection of files. More...
struct  ItemDesc
 Represents a single download source from which an item should be downloaded. More...
struct  MethodConfig
 Information about the properties of a single acquire method. {{{. More...
class  Queue
 A single download queue in a pkgAcquire object. {{{. More...
class  UriIterator
 Iterates over all the URIs being fetched by a pkgAcquire object. {{{. More...
class  Worker
 A fetch subprocess. More...

Public Types

enum  RunResult { Continue, Failed, Cancelled }
 

Provides information on how a download terminated.

More...
typedef vector< Item * >::iterator ItemIterator
typedef vector< Item * >
::const_iterator 
ItemCIterator

Public Member Functions

MethodConfigGetConfig (string Access)
 Retrieve information about a fetch method by name.
RunResult Run (int PulseInterval=500000)
 Download all the items that have been Add()ed to this download process.
void Shutdown ()
 Remove all items from this download process, terminate all download workers, and empty all queues.
WorkerWorkersBegin ()
 Get the first #Worker object.
WorkerWorkerStep (Worker *I)
 Advance to the next #Worker object.
ItemIterator ItemsBegin ()
 Get the head of the list of items.
ItemIterator ItemsEnd ()
 Get the end iterator of the list of items.
UriIterator UriBegin ()
 Get the head of the list of enqueued item URIs.
UriIterator UriEnd ()
 Get the end iterator of the list of enqueued item URIs.
bool Clean (string Dir)
unsigned long long TotalNeeded ()
unsigned long long FetchNeeded ()
unsigned long long PartialPresent ()
bool Setup (pkgAcquireStatus *Progress=NULL, string const &Lock="")
 Delayed constructor.
 pkgAcquire (pkgAcquireStatus *Log) __deprecated
 Construct a new pkgAcquire.
virtual ~pkgAcquire ()
 Destroy this pkgAcquire object.

Protected Types

enum  QueueStrategy { QueueHost, QueueAccess }
 

Represents the queuing strategy for remote URIs.

More...

Protected Member Functions

void Add (Item *Item)
 Add the given item to the list of items.
void Remove (Item *Item)
 Remove the given item from the list of items.
void Add (Worker *Work)
 Add the given worker to the list of workers.
void Remove (Worker *Work)
 Remove the given worker from the list of workers.
void Enqueue (ItemDesc &Item)
 Insert the given fetch request into the appropriate queue.
void Dequeue (Item *Item)
 Remove all fetch requests for this item from all queues.
string QueueName (string URI, MethodConfig const *&Config)
 Determine the fetch method and queue of a URI.
virtual void SetFds (int &Fd, fd_set *RSet, fd_set *WSet)
 Build up the set of file descriptors upon which select() should block.
virtual void RunFds (fd_set *RSet, fd_set *WSet)
void Bump ()
 Check for idle queues with ready-to-fetch items.

Protected Attributes

vector< Item * > Items
 A list of items to download.
QueueQueues
 The head of the list of active queues.
WorkerWorkers
 The head of the list of active workers.
MethodConfigConfigs
 The head of the list of acquire method configurations.
pkgAcquireStatusLog
 The progress indicator for this download.
unsigned long ToFetch
 The total size of the files which are to be fetched.
enum pkgAcquire::QueueStrategy QueueMode
bool const Debug
 If true, debugging information will be dumped to std::clog.
bool Running
 If true, a download is currently in progress.

Friends

class Item
class Queue

Detailed Description

The core download scheduler. {{{.

This class represents an ongoing download. It manages the lists of active and pending downloads and handles setting up and tearing down download-related structures.

Todo:
Why all the protected data items and methods?

Member Enumeration Documentation

enum QueueStrategy [protected]

Represents the queuing strategy for remote URIs.

Enumerator:
QueueHost 

Generate one queue for each protocol/host combination; downloads from multiple hosts can proceed in parallel.

QueueAccess 

Generate a single queue for each protocol; serialize downloads from multiple hosts.

enum RunResult

Provides information on how a download terminated.

Enumerator:
Continue 

All files were fetched successfully.

Failed 

Some files failed to download.

Cancelled 

The download was cancelled by the user (i.e., Log's pkgAcquireStatus::Pulse() method returned false).


Constructor & Destructor Documentation

~pkgAcquire ( ) [virtual]

Destroy this pkgAcquire object.

Destroys all queue, method, and item objects associated with this download.

References Configs, pkgAcquire::MethodConfig::Next, and Shutdown().


Member Function Documentation

void Bump ( ) [protected]

Check for idle queues with ready-to-fetch items.

Called by pkgAcquire::Queue::Done each time an item is dequeued but remains on some queues; i.e., another queue should start fetching it.

References Queues.

bool Clean ( string  Dir)

Deletes each entry in the given directory that is not being downloaded by this object. For instance, when downloading new list files, calling Clean() will delete the old ones.

Parameters:
DirThe directory to be cleaned out.
Returns:
true if the directory exists and is readable.

References Items.

void Enqueue ( ItemDesc Item) [protected]

Insert the given fetch request into the appropriate queue.

Parameters:
ItemThe URI to download and the item to download it for. Copied by value into the queue; no reference to Item is retained.

References pkgAcquire::Item::Complete, Debug, pkgAcquire::Item::DestFile, pkgAcquire::Queue::Enqueue(), pkgAcquire::Item::Local, pkgAcquire::MethodConfig::LocalOnly, pkgAcquire::Queue::Name, pkgAcquire::ItemDesc::Owner, QueueName(), Queues, Running, pkgAcquire::Queue::Startup(), pkgAcquire::Item::StatIdle, ToFetch, and pkgAcquire::ItemDesc::URI.

Referenced by pkgAcquire::Item::QueueURI().

unsigned long long FetchNeeded ( )
Returns:
the size in bytes of all non-local items included in this download.

References ItemsBegin(), and ItemsEnd().

pkgAcquire::MethodConfig * GetConfig ( string  Access)

Retrieve information about a fetch method by name.

Parameters:
AccessThe name of the method to look up.
Returns:
the method whose name is Access, or NULL if no such method exists.

References pkgAcquire::MethodConfig::Access, Configs, pkgAcquire::MethodConfig::Next, pkgAcquire::MethodConfig::SingleInstance, and pkgAcquire::Worker::Start().

Referenced by QueueName().

unsigned long long PartialPresent ( )
Returns:
the amount of data to be fetched that is already present on the filesystem.

References ItemsBegin(), and ItemsEnd().

string QueueName ( string  URI,
MethodConfig const *&  Config 
) [protected]

Determine the fetch method and queue of a URI.

Parameters:
URIThe URI to fetch.
[out]ConfigA location in which to place the method via which the URI is to be fetched.
Returns:
the string-name of the queue in which a fetch request for the given URI should be placed.

References GetConfig(), QueueAccess, and pkgAcquire::MethodConfig::SingleInstance.

Referenced by Enqueue().

pkgAcquire::RunResult Run ( int  PulseInterval = 500000)

Download all the items that have been Add()ed to this download process.

This method will block until the download completes, invoking methods on Log to report on the progress of the download.

Parameters:
PulseIntervalThe method pkgAcquireStatus::Pulse will be invoked on Log at intervals of PulseInterval milliseconds.
Returns:
the result of the download.

References Cancelled, Continue, Failed, Items, Log, pkgAcquire::Worker::NextAcquire, pkgAcquireStatus::Pulse(), Queues, RunFds(), Running, SetFds(), pkgAcquireStatus::Start(), pkgAcquireStatus::Stop(), ToFetch, pkgAcquireStatus::Update, and Workers.

void RunFds ( fd_set *  RSet,
fd_set *  WSet 
) [protected, virtual]

Handle input from and output to file descriptors which select() has determined are ready. The default implementation dispatches to all active downloads.

Parameters:
RSetThe set of file descriptors that are ready for input.
WSetThe set of file descriptors that are ready for output.

References pkgAcquire::Worker::NextAcquire, and Workers.

Referenced by Run().

void SetFds ( int &  Fd,
fd_set *  RSet,
fd_set *  WSet 
) [protected, virtual]

Build up the set of file descriptors upon which select() should block.

The default implementation inserts the file descriptors corresponding to active downloads.

Parameters:
[out]FdThe largest file descriptor in the generated sets.
[out]RSetThe set of file descriptors that should be watched for input.
[out]WSetThe set of file descriptors that should be watched for output.

References pkgAcquire::Worker::NextAcquire, and Workers.

Referenced by Run().

bool Setup ( pkgAcquireStatus Progress = NULL,
string const &  Lock = "" 
)

Delayed constructor.

Parameters:
Progressindicator associated with this download or NULL for none. This object is not owned by the download process and will not be deleted when the pkgAcquire object is destroyed. Naturally, it should live for at least as long as the pkgAcquire object does.
Lockdefines a lock file that should be acquired to ensure only one Acquire class is in action at the time or an empty string if no lock file should be used.

References Log.

Referenced by pkgAcquire().

unsigned long long TotalNeeded ( )
Returns:
the total size in bytes of all the items included in this download.

References ItemsBegin(), and ItemsEnd().

Get the head of the list of enqueued item URIs.

This iterator will step over every element of every active queue.

References Queues.

Worker* WorkersBegin ( ) [inline]

Get the first #Worker object.

Returns:
the first active worker in this download process.

References Workers.

Referenced by pkgAcquireStatus::Pulse().

pkgAcquire::Worker * WorkerStep ( Worker I)

Advance to the next #Worker object.

Returns:
the worker immediately following I, or NULL if none exists.

References pkgAcquire::Worker::NextAcquire.

Referenced by pkgAcquireStatus::Pulse().


Member Data Documentation

MethodConfig* Configs [protected]

The head of the list of acquire method configurations.

Each protocol (http, ftp, gzip, etc) via which files can be fetched can have a representation in this list. The configuration data is filled in by parsing the 100 Capabilities string output by a method on startup (see pkgAcqMethod::pkgAcqMethod and pkgAcquire::GetConfig).

Todo:
why a hand-managed config dictionary instead of std::map?

Referenced by GetConfig(), and ~pkgAcquire().

vector<Item *> Items [protected]

A list of items to download.

This is built monotonically as items are created and only emptied when the download shuts down.

Referenced by Add(), Clean(), pkgAcquire::Queue::Cycle(), pkgAcquire::Queue::Dequeue(), pkgAcquire::Queue::Enqueue(), pkgAcquire::Queue::FindItem(), ItemsBegin(), ItemsEnd(), Remove(), Run(), Shutdown(), and pkgAcquire::Queue::~Queue().

Queue* Queues [protected]

The head of the list of active queues.

Todo:
why a hand-managed list of queues instead of std::list or std::set?

Referenced by Bump(), Dequeue(), Enqueue(), Run(), Shutdown(), and UriBegin().

unsigned long ToFetch [protected]

The total size of the files which are to be fetched.

This is not necessarily the total number of bytes to download when, e.g., download resumption and list updates via patches are taken into account.

Referenced by Dequeue(), Enqueue(), and Run().

Worker* Workers [protected]

The head of the list of active workers.

Todo:
why a hand-managed list of workers instead of std::list or std::set?

Referenced by Add(), pkgAcquire::Queue::Cycle(), Remove(), Run(), RunFds(), SetFds(), pkgAcquire::Queue::Shutdown(), pkgAcquire::Queue::Startup(), and WorkersBegin().


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