pkgAcquire::Worker Class Reference
Acquire system {{{

A fetch subprocess. More...

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

Inheritance diagram for pkgAcquire::Worker:
[legend]
Collaboration diagram for pkgAcquire::Worker:
[legend]

## Public Member Functions

bool | QueueItem (pkgAcquire::Queue::QItem *Item)
| Tell the subprocess to download the given item.
APT_HIDDEN bool | ReplyAux (pkgAcquire::ItemDesc const &Item)
bool | Start ()
| Start up the worker and fill in Config.
void | Pulse ()
| Update the worker statistics (CurrentSize, TotalSize, etc).
const MethodConfig * | GetConf () const
| Worker (Queue *OwnerQ, MethodConfig *Config, pkgAcquireStatus *Log)
| Create a new Worker to download files.
| Worker (MethodConfig *Config)
| Create a new Worker that should just retrieve information about the fetch method.
virtual | ~Worker ()
| Clean up this worker.
Public Member Functions inherited from WeakPointable
void | AddWeakPointer (WeakPointable **weakptr)
void | RemoveWeakPointer (WeakPointable **weakptr)
| ~WeakPointable ()

## Public Attributes

pkgAcquire::Queue::QItem * | CurrentItem
| The queue entry that is currently being downloaded.
std::string | Status
| The most recent status string received from the subprocess.

## Protected Member Functions

void | Construct ()
| Common code for the constructor.
bool | ReadMessages ()
| Retrieve any available messages from the subprocess.
bool | RunMessages ()
| Parse and dispatch pending messages.
bool | InFdReady ()
| Read and dispatch any pending messages from the subprocess.
bool | OutFdReady ()
| Send any pending commands to the subprocess.
bool | Capabilities (std::string Message)
| Handle a 100 Capabilities response from the subprocess.
bool | SendConfiguration ()
| Send a 601 Configuration message (containing the APT configuration) to the subprocess.
bool | MediaChange (std::string Message)
| Handle a 403 Media Change message.
bool | MethodFailure ()
| Invoked when the worked process dies unexpectedly.
void | ItemDone ()
| Invoked when a fetch job is completed, either successfully or unsuccessfully.

## Protected Attributes

Worker * | NextQueue
| The next link on the Queue list.
Worker * | NextAcquire
| The next link on the Acquire list.
Queue * | OwnerQ
| The Queue with which this worker is associated.
pkgAcquireStatus * | Log
| The download progress indicator to which progress messages should be sent.
MethodConfig * | Config
| The configuration of this method. On startup, the target of this pointer is filled in with basic data about the method, as reported by the worker.
std::string | Access
| The access method to be used by this worker.
pid_t | Process
| The PID of the subprocess.
int | InFd
| A file descriptor connected to the standard output of the subprocess.
int | OutFd
| A file descriptor connected to the standard input of the subprocess.
int | PrivSepSocketFd
| The socket to send SCM_RIGHTS message through.
int | PrivSepSocketFdChild
bool | InReady
| Set to true if the worker is in a state in which it might generate data or command responses.
bool | OutReady
| Set to true if the worker is in a state in which it is legal to send commands to it.
bool | Debug
std::vector< std::string > | MessageQueue
| The raw text values of messages received from the worker, in sequence.
std::string | OutQueue
| Buffers pending writes to the subprocess.

## Friends

class | pkgAcquire
class | Queue

## Detailed Description

A fetch subprocess.

A worker process is responsible for one stage of the fetch. This class encapsulates the communications protocol between the master process and the worker, from the master end.

Each worker is intrinsically placed on two linked lists. The Queue list (maintained in the NextQueue variable) is maintained by the pkgAcquire::Queue class; it represents the set of workers assigned to a particular queue. The Acquire list (maintained in the NextAcquire variable) is maintained by the pkgAcquire class; it represents the set of active workers for a particular pkgAcquire object.

Todo
  Like everything else in the Acquire system, this has way too many protected items.

See also
  pkgAcqMethod, pkgAcquire::Item, pkgAcquire

## Constructor & Destructor Documentation

## Worker() [1/2]

Worker | ( | Queue * | OwnerQ,
|  | MethodConfig * | Config,
|  | pkgAcquireStatus * | Log )

Create a new Worker to download files.

Parameters

  OwnerQ | The queue into which this worker should be placed.
  Config | A location in which to store information about the fetch method.
  Log | The download progress indicator that should be used to report the progress of this worker.

References Access, Config, Construct(), CurrentItem, Log, and OwnerQ.

Referenced by Worker().

## Worker() [2/2]

Worker | ( | MethodConfig * | Config | ) |

explicit

Create a new Worker that should just retrieve information about the fetch method.

Nothing in particular forces you to refrain from actually downloading stuff, but the various status callbacks won't be invoked.

Parameters

  Config | A location in which to store information about the fetch method.

References Worker().

## ~Worker()

~Worker | ( |  | ) |

virtual

Clean up this worker.

Closes the file descriptors; if MethodConfig::NeedsCleanup is false, also rudely interrupts the worker with a SIGINT.

References Access, Config, InFd, OutFd, and Process.

## Member Function Documentation

## Capabilities()

bool Capabilities | ( | std::string | Message | ) |

protected

Handle a 100 Capabilities response from the subprocess.

Parameters

  Message | the raw text of the message from the subprocess.

The message will be parsed and its contents used to fill Config. If Config is NULL, this routine is a NOP.

Returns
  true.

References Config, and Debug.

Referenced by RunMessages().

## Construct()

void Construct | ( |  | ) |

protected

Common code for the constructor.

Initializes NextQueue and NextAcquire to NULL; Process, InFd, and OutFd to -1, OutReady and InReady to false, and Debug from _config.

References Debug, InFd, InReady, NextAcquire, NextQueue, OutFd, OutReady, and Process.

Referenced by Worker().

## GetConf()

const MethodConfig * GetConf | ( |  | ) | const

inline

Returns
  The fetch method configuration.

References Config.

Referenced by pkgAcquire::Queue::Shutdown().

## InFdReady()

bool InFdReady | ( |  | ) |

protected

Read and dispatch any pending messages from the subprocess.

Returns
  false if the subprocess died unexpectedly while a message was being transmitted.

References ReadMessages(), and RunMessages().

## ItemDone()

void ItemDone | ( |  | ) |

protected

Invoked when a fetch job is completed, either successfully or unsuccessfully.

Resets the status information for the worker process.

References CurrentItem, and Status.

Referenced by RunMessages().

## MediaChange()

bool MediaChange | ( | std::string | Message | ) |

protected

Handle a 403 Media Change message.

Parameters

  Message | the raw text of the message; the Media field indicates what type of media should be changed, and the Drive field indicates where the media is located.

Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the user to swap disks; informs the subprocess of the result (via 603 Media Changed, with the Failed field set to true if the user cancelled the media change).

References Access, Debug, Log, OutQueue, and OutReady.

Referenced by RunMessages().

## MethodFailure()

bool MethodFailure | ( |  | ) |

protected

Invoked when the worked process dies unexpectedly.

Waits for the subprocess to terminate and generates an error if it terminated abnormally, then closes and blanks out all file descriptors. Discards all pending messages from the subprocess.

Returns
  false.

References Access, InFd, InReady, MessageQueue, OutFd, OutQueue, OutReady, and Process.

Referenced by OutFdReady(), and ReadMessages().

## OutFdReady()

bool OutFdReady | ( |  | ) |

protected

Send any pending commands to the subprocess.

This method will fail if there is no pending output.

Returns
  true if all commands were succeeded, false if an error occurred (in which case MethodFailure() will be invoked).

References MethodFailure(), OutFd, OutQueue, and OutReady.

## QueueItem()

bool QueueItem | ( | pkgAcquire::Queue::QItem * | Item | ) |

Tell the subprocess to download the given item.

Parameters

  Item | the item to queue up.

Returns
  true if the item was successfully enqueued.

Queues up a 600 URI Acquire message for the given item to be sent at the next possible moment. Does not flush the output queue.

References Access, HashStringList::begin(), Config, pkgAcquire::Item::Custom600Headers(), Debug, HashStringList::end(), HashStringList::FileSize(), pkgAcquire::Item::GetExpectedHashes(), OutFd, OutQueue, OutReady, and pkgAcquire::Item::Owner.

## ReadMessages()

bool ReadMessages | ( |  | ) |

protected

Retrieve any available messages from the subprocess.

The messages are retrieved as in ReadMessages(), and MethodFailure() is invoked if an error occurs; in particular, if the pipe to the subprocess dies unexpectedly while a message is being read.

Returns
  true if the messages were successfully read, false otherwise.

References InFd, MessageQueue, MethodFailure(), and ReadMessages().

Referenced by InFdReady(), ReadMessages(), and Start().

## RunMessages()

bool RunMessages | ( |  | ) |

protected

Parse and dispatch pending messages.

This dispatches the message in a manner appropriate for its type.

Todo
  Several message types lack separate handlers.

See also
  Capabilities(), SendConfiguration(), MediaChange()

References Access, Capabilities(), pkgAcquire::Item::Complete, Config, CurrentItem, pkgAcquire::Queue::QItem::CurrentSize, Debug, pkgAcquire::ItemDesc::Description, pkgAcquire::Item::DescURI(), pkgAcquire::Item::DestFile, HashStringList::empty(), HashStringList::FileSize(), pkgAcquire::Queue::QItem::GetExpectedHashes(), ItemDone(), pkgAcquire::Item::Local, Log, MediaChange(), MessageQueue, OutQueue, OutReady, pkgAcquire::ItemDesc::Owner, OwnerQ, pkgAcquire::Queue::QItem::Owners, HashStringList::push_back(), pkgAcquire::Queue::QItem::ResumePoint, pkgAcquire::Item::StatIdle, Status, pkgAcquire::Queue::QItem::TotalSize, pkgAcquire::ItemDesc::URI, and HashStringList::usable().

Referenced by InFdReady(), and Start().

## SendConfiguration()

bool SendConfiguration | ( |  | ) |

protected

Send a 601 Configuration message (containing the APT configuration) to the subprocess.

The APT configuration will be send to the subprocess in a message of the following form:

    601 Configuration
    Config-Item: Fully-Qualified-Item=Val
    Config-Item: Fully-Qualified-Item=Val
    ...

Returns
  true if the command was successfully sent, false otherwise.

References Access, Config, Debug, OutFd, OutQueue, and OutReady.

Referenced by Start().

## Start()

bool Start | ( |  | ) |

Start up the worker and fill in Config.

Reads the first message from the worker, which is assumed to be a 100 Capabilities message.

Returns
  true if all operations completed successfully.

References Access, Debug, InFd, InReady, OutFd, OutReady, OwnerQ, Process, ReadMessages(), RunMessages(), and SendConfiguration().

Referenced by pkgAcquire::GetConfig().

## Member Data Documentation

## Access

std::string Access

protected

The access method to be used by this worker.

Todo
  Doesn't this duplicate Config->Access?

Referenced by MediaChange(), MethodFailure(), QueueItem(), RunMessages(), SendConfiguration(), Start(), Worker(), and ~Worker().

## Debug

bool Debug

protected

If true, debugging output will be sent to std::clog.

Referenced by Capabilities(), Construct(), MediaChange(), QueueItem(), RunMessages(), SendConfiguration(), and Start().

## InFd

int InFd

protected

A file descriptor connected to the standard output of the subprocess.

Used to read messages and data from the subprocess.

Referenced by Construct(), MethodFailure(), ReadMessages(), Start(), and ~Worker().

## InReady

bool InReady

protected

Set to true if the worker is in a state in which it might generate data or command responses.

Todo
  Is this right? It's a guess.

Referenced by Construct(), MethodFailure(), and Start().

## NextQueue

Worker* NextQueue

protected

The next link on the Queue list.

Todo
  This is always NULL; is it just for future use?

Referenced by Construct(), and pkgAcquire::Queue::Shutdown().

## OutFd

int OutFd

protected

A file descriptor connected to the standard input of the subprocess.

Used to send commands and configuration data to the subprocess.

Referenced by Construct(), MethodFailure(), OutFdReady(), QueueItem(), SendConfiguration(), Start(), and ~Worker().

## OutQueue

std::string OutQueue

protected

Buffers pending writes to the subprocess.

Todo
  Wouldn't a std::dequeue be more appropriate?

Referenced by MediaChange(), MethodFailure(), OutFdReady(), QueueItem(), RunMessages(), and SendConfiguration().

## OutReady

bool OutReady

protected

Set to true if the worker is in a state in which it is legal to send commands to it.

Todo
  Is this right?

Referenced by Construct(), MediaChange(), MethodFailure(), OutFdReady(), QueueItem(), RunMessages(), SendConfiguration(), and Start().

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

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