apt @VERSION@
Public Member Functions | Public Attributes | Protected Member Functions | Protected Attributes | Friends

pkgAcquire::Worker Class Reference

A fetch subprocess. More...

#include <acquire-worker.h>

Inheritance diagram for pkgAcquire::Worker:
WeakPointable

List of all members.

Public Member Functions

bool QueueItem (pkgAcquire::Queue::QItem *Item)
 Tell the subprocess to download the given item.
bool Start ()
 Start up the worker and fill in Config.
void Pulse ()
 Update the worker statistics (CurrentSize, TotalSize, etc).
const MethodConfigGetConf () 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.
 ~Worker ()
 Clean up this worker.

Public Attributes

pkgAcquire::Queue::QItemCurrentItem
 The queue entry that is currently being downloaded.
string Status
 The most recent status string received from the subprocess.
unsigned long CurrentSize
 How many bytes of the file have been downloaded. Zero if the current progress of the file cannot be determined.
unsigned long TotalSize
 The total number of bytes to be downloaded. Zero if the total size of the final is unknown.
unsigned long ResumePoint
 How much of the file was already downloaded prior to starting this worker.

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

WorkerNextQueue
 The next link on the Queue list.
WorkerNextAcquire
 The next link on the Acquire list.
QueueOwnerQ
 The Queue with which this worker is associated.
pkgAcquireStatusLog
 The download progress indicator to which progress messages should be sent.
MethodConfigConfig
 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.
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.
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
vector< string > MessageQueue
 The raw text values of messages received from the worker, in sequence.
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 ( Queue OwnerQ,
MethodConfig Config,
pkgAcquireStatus Log 
)

Create a new Worker to download files.

Parameters:
OwnerQThe queue into which this worker should be placed.
ConfigA location in which to store information about the fetch method.
LogThe download progress indicator that should be used to report the progress of this worker.

References pkgAcquire::MethodConfig::Access, Access, Config, Construct(), CurrentItem, CurrentSize, OwnerQ, and TotalSize.

Worker ( MethodConfig Config)

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:
ConfigA location in which to store information about the fetch method.

References pkgAcquire::MethodConfig::Access.

~Worker ( )

Clean up this worker.

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


Member Function Documentation

bool Capabilities ( string  Message) [protected]

Handle a 100 Capabilities response from the subprocess.

Parameters:
Messagethe 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 pkgAcquire::Debug.

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

Referenced by Worker().

const MethodConfig* GetConf ( ) const [inline]
Returns:
The fetch method configuration.

References Config.

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

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.
void ItemDone ( ) [protected]

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

Resets the status information for the worker process.

bool MediaChange ( string  Message) [protected]

Handle a 403 Media Change message.

Parameters:
Messagethe 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).

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.
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).
bool QueueItem ( pkgAcquire::Queue::QItem Item)

Tell the subprocess to download the given item.

Parameters:
Itemthe 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 pkgAcquire::Item::Custom600Headers(), pkgAcquire::Debug, pkgAcquire::Item::DestFile, pkgAcquire::ItemDesc::Owner, and pkgAcquire::ItemDesc::URI.

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

bool ReadMessages ( ) [protected]

Retrieve any available messages from the subprocess.

The messages are retrieved as in ::ReadMessages(), and MessageFailure() 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.
bool RunMessages ( ) [protected]
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 pkgAcquire::Debug.

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

Referenced by pkgAcquire::GetConfig(), and pkgAcquire::Queue::Startup().


Member Data Documentation

string Access [protected]

The access method to be used by this worker.

Todo:
Doesn't this duplicate Config->Access?

Referenced by Worker().

bool Debug [protected]

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

int InFd [protected]

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

Used to read messages and data from the subprocess.

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.
Worker* NextQueue [protected]

The next link on the Queue list.

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

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

int OutFd [protected]

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

Used to send commands and configuration data to the subprocess.

string OutQueue [protected]

Buffers pending writes to the subprocess.

Todo:
Wouldn't a std::dequeue be more appropriate?
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?

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