apt: pkgAcquire Class Reference

apt 3.0.1 commandline package manager

Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | Friends | List of all members
pkgAcquire Class Reference
Acquire system {{{

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

`#include <apt-pkg/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
MethodConfig * | GetConfig (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.
Worker * | WorkersBegin ()
| Get the first Worker object.
Worker * | WorkerStep (Worker *I) APT_PURE
| Advance to the next Worker object.
ItemIterator | ItemsBegin ()
| Get the head of the list of items.
ItemCIterator | ItemsBegin () const
ItemIterator | ItemsEnd ()
| Get the end iterator of the list of items.
ItemCIterator | ItemsEnd () const
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)
bool | CleanLists (std::string const &Dir)
unsigned long long | TotalNeeded ()
unsigned long long | FetchNeeded ()
unsigned long long | PartialPresent ()
void | SetLog (pkgAcquireStatus *Progress)
bool | GetLock (std::string const &Lock)
| acquire lock and perform directory setup
| pkgAcquire (pkgAcquireStatus *Log)
| Construct a new pkgAcquire.
virtual | ~pkgAcquire ()
| Destroy this pkgAcquire object.

## Static Public Member Functions
static APT_HIDDEN std::string | URIEncode (std::string const &part)

## 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 bool | 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.
Queue * | Queues
| The head of the list of active queues.
Worker * | Workers
| The head of the list of active workers.
MethodConfig * | Configs
| The head of the list of acquire method configurations.
pkgAcquireStatus * | Log
| 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 | pkgAcqMetaBase
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

## ◆ QueueStrategy

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.

## ◆ RunResult

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

~pkgAcquire | ( |  | ) |
| virtual

Destroy this pkgAcquire object.

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

References Configs, and Shutdown().

## Member Function Documentation

## ◆ Bump()

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.

## ◆ Clean()

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

  Dir | The directory to be cleaned out.

Returns
  true if the directory exists and is readable.

References Items.

## ◆ CleanLists()

bool CleanLists | ( | std::string const & | Dir | ) |

Deletes each package list and index file in the given directory.

Parameters

  Dir | The directory to be cleaned.

Returns
  true if the directory exists and is readable.

## ◆ Enqueue()

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

References Debug, pkgAcquire::MethodConfig::LocalOnly, Log, pkgAcquire::Item::Owner, QueueName(), Queues, Running, pkgAcquire::Item::StatError, pkgAcquire::Item::StatIdle, and ToFetch.

## ◆ FetchNeeded()

APT_PURE unsigned long long FetchNeeded | ( |  | ) |

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

References ItemsBegin(), and ItemsEnd().

## ◆ GetConfig()

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

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

Referenced by QueueName().

## ◆ GetLock()

bool GetLock | ( | std::string const & | Lock | ) |

acquire lock and perform directory setup

Parameters

  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. If set also all needed directories will be created and setup.

References GetLock().

Referenced by GetLock().

## ◆ PartialPresent()

APT_PURE unsigned long long PartialPresent | ( |  | ) |

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

References ItemsBegin(), and ItemsEnd().

## ◆ QueueName()

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

References HashStringList::FileSize(), GetConfig(), pkgAcquire::Queue::Name, QueueAccess, Queues, and pkgAcquire::MethodConfig::SingleInstance.

Referenced by Enqueue().

## ◆ Run()

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

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

Returns
  the result of the download.

References Cancelled, Continue, Failed, Items, Log, Queues, RunFds(), Running, SetFds(), pkgAcquire::Item::StatIdle, ToFetch, and Workers.

## ◆ RunFds()

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

Returns
  false if there is an error condition on one of the fds

References Workers.

Referenced by Run().

## ◆ SetFds()

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

References Workers.

Referenced by Run().

## ◆ TotalNeeded()

APT_PURE unsigned long long TotalNeeded | ( |  | ) |

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

References ItemsBegin(), and ItemsEnd().

## ◆ UriBegin()

pkgAcquire::UriIterator UriBegin | ( |  | ) |

Get the head of the list of enqueued item URIs.

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

References Queues.

## ◆ WorkersBegin()

Worker * WorkersBegin | ( |  | ) |
| inline

Get the first Worker object.

Returns
  the first active worker in this download process.

References Workers.

Referenced by pkgAcquireStatus::Pulse().

## ◆ WorkerStep()

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

## ◆ Configs

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(), pkgAcquire(), and ~pkgAcquire().

## ◆ Items

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(), ItemsBegin(), ItemsEnd(), Remove(), Run(), and Shutdown().

## ◆ Queues

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

## ◆ Workers

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(), Remove(), Run(), RunFds(), SetFds(), and WorkersBegin().

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

- apt-pkg/acquire.h
- apt-pkg/acquire.cc