apt  0.9.7.5ubuntu3
Classes | Public Types | Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Friends | List of all members
pkgAcquire Class Reference

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

#include <acquire.h>

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 std::vector< Item * >
::iterator 
ItemIterator
typedef std::vector< Item * >
::const_iterator 
ItemCIterator

Public Member Functions

MethodConfigGetConfig (std::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 (std::string Dir)
unsigned long long TotalNeeded ()
unsigned long long FetchNeeded ()
unsigned long long PartialPresent ()
bool Setup (pkgAcquireStatus *Progress=NULL, std::string const &Lock="")
 Delayed constructor.
void SetLog (pkgAcquireStatus *Progress)
 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.
std::string QueueName (std::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

std::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 number of 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 ( std::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 ( std::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 ( std::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 Debug, GetConfig(), pkgAcquire::Queue::Name, QueueAccess, Queues, 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 
)
protectedvirtual

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 
)
protectedvirtual

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,
std::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().

std::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(), QueueName(), Run(), Shutdown(), and UriBegin().

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: