apt: pkgAcquire::Queue Class Reference

apt 3.3.3 commandline package manager

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

A single download queue in a pkgAcquire object. {{{. More...

`#include <apt-pkg/acquire.h>`

## Classes
struct | QItem
| A single item placed in this queue. More...

## Public Member Functions
bool | Enqueue (ItemDesc &Item)
| Insert the given fetch request into this queue.
bool | Dequeue (Item *Owner)
| Remove all fetch requests for the given item from this queue.
QItem * | FindItem (std::string URI, pkgAcquire::Worker *Owner) APT_PURE
| Locate an item in this queue.
bool | ItemStart (QItem *Itm, unsigned long long Size)
bool | ItemDone (QItem *Itm)
| Remove the given item from this queue and set its state to pkgAcquire::Item::StatDone.
bool | Startup ()
| Start the worker process associated with this queue.
bool | Shutdown (bool Final)
| Shut down the worker process associated with this queue.
bool | Cycle ()
| Send idle items to the worker process.
void | Bump ()
| Check for items that could be enqueued.
| Queue (std::string const &Name, pkgAcquire *const Owner)
| Create a new Queue.
virtual | ~Queue ()

## Protected Attributes
std::string | Name
| The name of this queue.
QItem * | Items
| The head of the list of items contained in this queue.
pkgAcquire::Worker * | Workers
| The head of the list of workers associated with this queue.
pkgAcquire * | Owner
| the download scheduler with which this queue is associated.
signed long | PipeDepth
| The number of entries in this queue that are currently being downloaded.
unsigned long | MaxPipeDepth
| The maximum number of entries that this queue will attempt to download at once.

## Friends
class | pkgAcquire
class | pkgAcquire::UriIterator
class | pkgAcquire::Worker

## Detailed Description

A single download queue in a pkgAcquire object. {{{.

Todo
  Why so many protected values?

## Constructor & Destructor Documentation

## ◆ Queue()

Queue | ( | std::string const & | Name,
|  | pkgAcquire *const | Owner )

Create a new Queue.

Parameters

  Name | The name of the new queue.
  Owner | The download process that owns the new queue.

References Items, MaxPipeDepth, Name, Owner, PipeDepth, and Workers.

Referenced by ItemStart().

## ◆ ~Queue()

~Queue | ( |  | ) |
| virtual

Shut down all the worker processes associated with this queue and empty the queue.

References Items, and pkgAcquire::Shutdown().

## Member Function Documentation

## ◆ Bump()

void Bump | ( |  | ) |

Check for items that could be enqueued.

Call this after an item placed in multiple queues has gone from the pkgAcquire::Item::StatFetching state to the pkgAcquire::Item::StatIdle state, to possibly refill an empty queue. This is an alias for Cycle().

Todo
  Why both this and Cycle()? Are they expected to be different someday?

References Cycle().

Referenced by ItemStart().

## ◆ Cycle()

bool Cycle | ( |  | ) |

Send idle items to the worker process.

Fills up the pipeline by inserting idle items into the worker's queue.

References Items, MaxPipeDepth, PipeDepth, pkgAcquire::Item::StatFetching, pkgAcquire::Item::StatIdle, and Workers.

Referenced by Bump(), Enqueue(), ItemDone(), ItemStart(), and Startup().

## ◆ Dequeue()

bool Dequeue | ( | Item * | Owner | ) |

Remove all fetch requests for the given item from this queue.

Returns
  true if at least one request was removed from the queue.

References Items, pkgAcquire::Queue::QItem::Next, Owner, and pkgAcquire::Item::StatFetching.

## ◆ Enqueue()

bool Enqueue | ( | ItemDesc & | Item | ) |

Insert the given fetch request into this queue.

Returns
  true if the queuing was successful. May return false if the Item is already in the queue

References Cycle(), Items, pkgAcquire::Queue::QItem::Next, pkgAcquire::Item::Owner, and pkgAcquire::ItemDesc::Owner.

## ◆ FindItem()

pkgAcquire::Queue::QItem * FindItem | ( | std::string | URI,
|  | pkgAcquire::Worker * | Owner )

Locate an item in this queue.

Parameters

  URI | A URI to match against.
  Owner | A pkgAcquire::Worker to match against.

Returns
  the first item in the queue whose URI is URI and that is being downloaded by Owner.

References Items, and Owner.

## ◆ ItemDone()

bool ItemDone | ( | QItem * | Itm | ) |

Remove the given item from this queue and set its state to pkgAcquire::Item::StatDone.

If this is the only queue containing the item, the item is also removed from the main queue by calling pkgAcquire::Dequeue.

Parameters

  Itm | The item to remove.

Returns
  true if no errors are encountered.

References Cycle(), pkgAcquire::Dequeue(), pkgAcquire::ItemDesc::Owner, Owner, pkgAcquire::Queue::QItem::Owners, PipeDepth, pkgAcquire::Item::QueueCounter, pkgAcquire::Item::StatDone, and pkgAcquire::Item::StatFetching.

Referenced by ItemStart().

## ◆ ItemStart()

bool ItemStart | ( | QItem * | Itm,
|  | unsigned long long | Size )

Presumably this should start downloading an item?

Todo
  Unimplemented. Implement it or remove?

References Bump(), Cycle(), ItemDone(), Name, Owner, Queue(), Shutdown(), and Startup().

## ◆ Shutdown()

bool Shutdown | ( | bool | Final | ) |

Shut down the worker process associated with this queue.

Parameters

  Final | If true, then the process is stopped unconditionally. Otherwise, it is only stopped if it does not need cleanup as indicated by the pkgAcqMethod::NeedsCleanup member of its configuration.

Returns
  true.

References pkgAcquire::Worker::GetConf(), pkgAcquire::MethodConfig::NeedsCleanup, pkgAcquire::Worker::NextQueue, Owner, and Workers.

Referenced by ItemStart().

## ◆ Startup()

bool Startup | ( |  | ) |

Start the worker process associated with this queue.

If a worker process is already associated with this queue, this is equivalent to calling Cycle().

Returns
  true if the startup was successful.

References Cycle(), Items, MaxPipeDepth, Name, Owner, pkgAcquire::MethodConfig::Pipeline, and Workers.

Referenced by ItemStart().

## Member Data Documentation

## ◆ Items

QItem* Items
| protected

The head of the list of items contained in this queue.

Todo
  why a by-hand list instead of an STL structure?

Referenced by Cycle(), Dequeue(), Enqueue(), FindItem(), Queue(), Startup(), and ~Queue().

## ◆ Workers

pkgAcquire::Worker* Workers
| protected

The head of the list of workers associated with this queue.

Todo
  This is plural because support exists in Queue for multiple workers. However, it does not appear that there is any way to actually associate more than one worker with a queue.

Todo
  Why not just use a std::set?

Referenced by Cycle(), Queue(), Shutdown(), and Startup().

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

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