The core download scheduler. More...

#include <acquire.h>

Collaboration diagram for pkgAcquire:

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

typedef std::vector< Item * > ::iterator	ItemIterator

enum	RunResult { Continue, Failed, Cancelled }
	Provides information on how a download terminated. More...

Public Member Functions
	pkgAcquire (pkgAcquireStatus *Log) __deprecated
	Construct a new pkgAcquire. More...

	pkgAcquire ()

virtual	~pkgAcquire ()
	Destroy this pkgAcquire object. More...

bool	Clean (std::string Dir)
	Deletes each entry in the given directory that is not being downloaded by this object. More...

unsigned long long	FetchNeeded ()

MethodConfig *	GetConfig (std::string Access)
	Retrieve information about a fetch method by name. More...

ItemIterator	ItemsBegin ()
	Get the head of the list of items. More...

ItemIterator	ItemsEnd ()
	Get the end iterator of the list of items. More...

unsigned long long	PartialPresent ()

RunResult	Run (int PulseInterval=500000)
	Download all the items that have been Add()ed to this download process. More...

void	SetLog (pkgAcquireStatus *Progress)

bool	Setup (pkgAcquireStatus *Progress=NULL, std::string const &Lock="")
	Delayed constructor. More...

void	Shutdown ()
	Remove all items from this download process, terminate all download workers, and empty all queues. More...

unsigned long long	TotalNeeded ()

UriIterator	UriBegin ()
	Get the head of the list of enqueued item URIs. More...

UriIterator	UriEnd ()
	Get the end iterator of the list of enqueued item URIs. More...

Worker *	WorkersBegin ()
	Get the first #Worker object. More...

Worker *	WorkerStep (Worker *I)
	Advance to the next #Worker object. More...

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. More...

void	Add (Worker *Work)
	Add the given worker to the list of workers. More...

void	Bump ()
	Check for idle queues with ready-to-fetch items. More...

void	Dequeue (Item *Item)
	Remove all fetch requests for this item from all queues. More...

void	Enqueue (ItemDesc &Item)
	Insert the given fetch request into the appropriate queue. More...

std::string	QueueName (std::string URI, MethodConfig const *&Config)
	Determine the fetch method and queue of a URI. More...

void	Remove (Item *Item)
	Remove the given item from the list of items. More...

void	Remove (Worker *Work)
	Remove the given worker from the list of workers. More...

virtual void	RunFds (fd_set RSet, fd_set WSet)
	Handle input from and output to file descriptors which select() has determined are ready. More...

virtual void	SetFds (int &Fd, fd_set RSet, fd_set WSet)
	Build up the set of file descriptors upon which select() should block. More...

Protected Attributes
MethodConfig *	Configs
	The head of the list of acquire method configurations. More...

bool const	Debug
	If true, debugging information will be dumped to std::clog. More...

std::vector< Item * >	Items
	A list of items to download. More...

pkgAcquireStatus *	Log
	The progress indicator for this download. More...

enum pkgAcquire::QueueStrategy	QueueMode

Queue *	Queues
	The head of the list of active queues. More...

bool	Running
	If true, a download is currently in progress. More...

unsigned long	ToFetch
	The number of files which are to be fetched. More...

Worker *	Workers
	The head of the list of active workers. More...

Private Attributes
void *	d
	dpointer placeholder (for later in case we need it) More...

int	LockFD
	FD of the Lock file we acquire in Setup (if any) More...

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 Typedef Documentation

typedef std::vector<Item *>::const_iterator pkgAcquire::ItemCIterator

typedef std::vector<Item *>::iterator pkgAcquire::ItemIterator

Member Enumeration Documentation

enum pkgAcquire::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 pkgAcquire::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::pkgAcquire ( pkgAcquireStatus * Log )

Construct a new pkgAcquire.

pkgAcquire::pkgAcquire ( )

virtual pkgAcquire::~pkgAcquire ( )

virtual

Destroy this pkgAcquire object.

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

Member Function Documentation

void pkgAcquire::Add ( Item * Item )

protected

Add the given item to the list of items.

void pkgAcquire::Add ( Worker * Work )

protected

Add the given worker to the list of workers.

void pkgAcquire::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.

bool pkgAcquire::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

Dir	The directory to be cleaned out.

Returns: true if the directory exists and is readable.

void pkgAcquire::Dequeue ( Item * Item )

protected

Remove all fetch requests for this item from all queues.

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

Here is the caller graph for this function:

void pkgAcquire::Enqueue ( ItemDesc & Item )

protected

Insert the given fetch request into the appropriate queue.

Parameters

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

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

Here is the caller graph for this function:

unsigned long long pkgAcquire::FetchNeeded ( )

Returns: the size in bytes of all non-local items included in this download.

MethodConfig* pkgAcquire::GetConfig ( std::string Access )

Retrieve information about a fetch method by name.

Parameters

Access The name of the method to look up.

Returns: the method whose name is Access, or NULL if no such method exists.

ItemIterator pkgAcquire::ItemsBegin ( )

inline

Get the head of the list of items.

References Items.

ItemIterator pkgAcquire::ItemsEnd ( )

inline

Get the end iterator of the list of items.

References Items.

unsigned long long pkgAcquire::PartialPresent ( )

Returns: the amount of data to be fetched that is already present on the filesystem.

std::string pkgAcquire::QueueName	(	std::string	URI,
		MethodConfig const *&	Config
	)

protected

Determine the fetch method and queue of a URI.

Parameters

	URI	The URI to fetch.
[out]	Config	A 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.

void pkgAcquire::Remove ( Item * Item )

protected

Remove the given item from the list of items.

void pkgAcquire::Remove ( Worker * Work )

protected

Remove the given worker from the list of workers.

RunResult pkgAcquire::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

PulseInterval The method pkgAcquireStatus::Pulse will be invoked on Log at intervals of PulseInterval milliseconds.

Returns: the result of the download.

virtual void pkgAcquire::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

RSet	The set of file descriptors that are ready for input.
WSet	The set of file descriptors that are ready for output.

virtual void pkgAcquire::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]	Fd	The largest file descriptor in the generated sets.
[out]	RSet	The set of file descriptors that should be watched for input.
[out]	WSet	The set of file descriptors that should be watched for output.

void pkgAcquire::SetLog ( pkgAcquireStatus * Progress )

inline

References Log.

bool pkgAcquire::Setup	(	pkgAcquireStatus *	Progress = `NULL`,
		std::string const &	Lock = `""`
	)

Delayed constructor.

Parameters

Progress	indicator 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.
Lock	defines 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.

void pkgAcquire::Shutdown ( )

Remove all items from this download process, terminate all download workers, and empty all queues.

unsigned long long pkgAcquire::TotalNeeded ( )

Returns: the total size in bytes of all the items included in this download.

UriIterator pkgAcquire::UriBegin ( )

Get the head of the list of enqueued item URIs.

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

UriIterator pkgAcquire::UriEnd ( )

Get the end iterator of the list of enqueued item URIs.

Worker* pkgAcquire::WorkersBegin ( )

inline

Get the first #Worker object.

Returns: the first active worker in this download process.

References Workers.

Worker* pkgAcquire::WorkerStep ( Worker * I )

Advance to the next #Worker object.

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

Friends And Related Function Documentation

friend class Item

friend

friend class Queue

friend

Member Data Documentation

MethodConfig* pkgAcquire::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?

void* pkgAcquire::d

private

dpointer placeholder (for later in case we need it)

bool const pkgAcquire::Debug

protected

If true, debugging information will be dumped to std::clog.

std::vector<Item *> pkgAcquire::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 ItemsBegin(), and ItemsEnd().

int pkgAcquire::LockFD

private

FD of the Lock file we acquire in Setup (if any)

pkgAcquireStatus* pkgAcquire::Log

protected

The progress indicator for this download.

Referenced by SetLog().

enum pkgAcquire::QueueStrategy pkgAcquire::QueueMode

protected

Queue* pkgAcquire::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?

bool pkgAcquire::Running

protected

If true, a download is currently in progress.

unsigned long pkgAcquire::ToFetch

protected

The number of files which are to be fetched.

Worker* pkgAcquire::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 WorkersBegin().

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

/usr/include/apt-pkg/acquire.h

Classes

Public Types

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Private Attributes

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation