apt-pkg/acquire-worker.h

   1 // -*- mode: cpp; mode: fold -*-
   2 // Description                                                          /*{{{*/
   3 // $Id: acquire-worker.h,v 1.12 2001/02/20 07:03:17 jgg Exp $
   4 /* ######################################################################
   5
   6    Acquire Worker - Worker process manager
   7
   8    Each worker class is associated with exaclty one subprocess.
   9
  10    ##################################################################### */
  11                                                                         /*}}}*/
  12
  13 /** \addtogroup acquire
  14  *  @{
  15  *
  16  *  \file acquire-worker.h
  17  */
  18
  19 #ifndef PKGLIB_ACQUIRE_WORKER_H
  20 #define PKGLIB_ACQUIRE_WORKER_H
  21
  22 #include <apt-pkg/acquire.h>
  23
  24 #ifdef __GNUG__
  25 #pragma interface "apt-pkg/acquire-worker.h"
  26 #endif
  27
  28 /** \brief A fetch subprocess.
  29  *
  30  *  A worker process is responsible for one stage of the fetch.  This
  31  *  class encapsulates the communications protocol between the master
  32  *  process and the worker, from the master end.
  33  *
  34  *  Each worker is intrinsically placed on two linked lists.  The
  35  *  Queue list (maintained in the #NextQueue variable) is maintained
  36  *  by the pkgAcquire::Queue class; it represents the set of workers
  37  *  assigned to a particular queue.  The Acquire list (maintained in
  38  *  the #NextAcquire variable) is maintained by the pkgAcquire class;
  39  *  it represents the set of active workers for a particular
  40  *  pkgAcquire object.
  41  *
  42  *  \todo Like everything else in the Acquire system, this has way too
  43  *  many protected items.
  44  *
  45  *  \sa pkgAcqMethod, pkgAcquire::Item, pkgAcquire
  46  */
  47 class pkgAcquire::Worker
  48 {
  49    friend class pkgAcquire;
  50
  51    protected:
  52    friend class Queue;
  53
  54    /** \brief The next link on the Queue list.
  55     *
  56     *  \todo This is always NULL; is it just for future use?
  57     */
  58    Worker *NextQueue;
  59
  60    /** \brief The next link on the Acquire list. */
  61    Worker *NextAcquire;
  62
  63    /** \brief The Queue with which this worker is associated. */
  64    Queue *OwnerQ;
  65
  66    /** \brief The download progress indicator to which progress
  67     *  messages should be sent.
  68     */
  69    pkgAcquireStatus *Log;
  70
  71    /** \brief The configuration of this method.  On startup, the
  72     *  target of this pointer is filled in with basic data about the
  73     *  method, as reported by the worker.
  74     */
  75    MethodConfig *Config;
  76
  77    /** \brief The access method to be used by this worker.
  78     *
  79     *  \todo Doesn't this duplicate Config->Access?
  80     */
  81    string Access;
  82
  83    /** \brief The PID of the subprocess. */
  84    pid_t Process;
  85
  86    /** \brief A file descriptor connected to the standard output of
  87     *  the subprocess.
  88     *
  89     *  Used to read messages and data from the subprocess.
  90     */
  91    int InFd;
  92
  93    /** \brief A file descriptor connected to the standard input of the
  94     *  subprocess.
  95     *
  96     *  Used to send commands and configuration data to the subprocess.
  97     */
  98    int OutFd;
  99
 100    /** \brief Set to \b true if the worker is in a state in which it
 101     *  might generate data or command responses.
 102     *
 103     *  \todo Is this right?  It's a guess.
 104     */
 105    bool InReady;
 106
 107    /** \brief Set to \b true if the worker is in a state in which it
 108     *  is legal to send commands to it.
 109     *
 110     *  \todo Is this right?
 111     */
 112    bool OutReady;
 113
 114    /** If \b true, debugging output will be sent to std::clog. */
 115    bool Debug;
 116
 117    /** \brief The raw text values of messages received from the
 118     *  worker, in sequence.
 119     */
 120    vector<string> MessageQueue;
 121
 122    /** \brief Buffers pending writes to the subprocess.
 123     *
 124     *  \todo Wouldn't a std::dequeue be more appropriate?
 125     */
 126    string OutQueue;
 127
 128    /** \brief Common code for the constructor.
 129     *
 130     *  Initializes NextQueue and NextAcquire to NULL; Process, InFd,
 131     *  and OutFd to -1, OutReady and InReady to \b false, and Debug
 132     *  from _config.
 133     */
 134    void Construct();
 135
 136    /** \brief Retrieve any available messages from the subprocess.
 137     *
 138     *  The messages are retrieved as in ::ReadMessages(), and
 139     *  MessageFailure() is invoked if an error occurs; in particular,
 140     *  if the pipe to the subprocess dies unexpectedly while a message
 141     *  is being read.
 142     *
 143     *  \return \b true if the messages were successfully read, \b
 144     *  false otherwise.
 145     */
 146    bool ReadMessages();
 147
 148    /** \brief Parse and dispatch pending messages.
 149     *
 150     *  This dispatches the message in a manner appropriate for its
 151     *  type.
 152     *
 153     *  \todo Several message types lack separate handlers.
 154     *
 155     *  \sa Capabilities(), SendConfiguration(), MediaChange()
 156     */
 157    bool RunMessages();
 158
 159    /** \brief Read and dispatch any pending messages from the
 160     *  subprocess.
 161     *
 162     *  \return \b false if the subprocess died unexpectedly while a
 163     *  message was being transmitted.
 164     */
 165    bool InFdReady();
 166
 167    /** \brief Send any pending commands to the subprocess.
 168     *
 169     *  This method will fail if there is no pending output.
 170     *
 171     *  \return \b true if all commands were succeeded, \b false if an
 172     *  error occurred (in which case MethodFailure() will be invoked).
 173     */
 174    bool OutFdReady();
 175
 176    /** \brief Handle a 100 Capabilities response from the subprocess.
 177     *
 178     *  \param Message the raw text of the message from the subprocess.
 179     *
 180     *  The message will be parsed and its contents used to fill
 181     *  #Config.  If #Config is NULL, this routine is a NOP.
 182     *
 183     *  \return \b true.
 184     */
 185    bool Capabilities(string Message);
 186
 187    /** \brief Send a 601 Configuration message (containing the APT
 188     *  configuration) to the subprocess.
 189     *
 190     *  The APT configuration will be send to the subprocess in a
 191     *  message of the following form:
 192     *
 193     *  <pre>
 194     *  601 Configuration
 195     *  Config-Item: Fully-Qualified-Item=Val
 196     *  Config-Item: Fully-Qualified-Item=Val
 197     *  ...
 198     *  </pre>
 199     *
 200     *  \return \b true if the command was successfully sent, \b false
 201     *  otherwise.
 202     */
 203    bool SendConfiguration();
 204
 205    /** \brief Handle a 403 Media Change message.
 206     *
 207     *  \param Message the raw text of the message; the Media field
 208     *  indicates what type of media should be changed, and the Drive
 209     *  field indicates where the media is located.
 210     *
 211     *  Invokes pkgAcquireStatus::MediaChange(Media, Drive) to ask the
 212     *  user to swap disks; informs the subprocess of the result (via
 213     *  603 Media Changed, with the Failed field set to \b true if the
 214     *  user cancelled the media change).
 215     */
 216    bool MediaChange(string Message);
 217
 218    /** \brief Invoked when the worked process dies unexpectedly.
 219     *
 220     *  Waits for the subprocess to terminate and generates an error if
 221     *  it terminated abnormally, then closes and blanks out all file
 222     *  descriptors.  Discards all pending messages from the
 223     *  subprocess.
 224     *
 225     *  \return \b false.
 226     */
 227    bool MethodFailure();
 228
 229    /** \brief Invoked when a fetch job is completed, either
 230     *  successfully or unsuccessfully.
 231     *
 232     *  Resets the status information for the worker process.
 233     */
 234    void ItemDone();
 235
 236    public:
 237
 238    /** \brief The queue entry that is currently being downloaded. */
 239    pkgAcquire::Queue::QItem *CurrentItem;
 240
 241    /** \brief The most recent status string received from the
 242     *  subprocess.
 243     */
 244    string Status;
 245
 246    /** \brief How many bytes of the file have been downloaded.  Zero
 247     *  if the current progress of the file cannot be determined.
 248     */
 249    unsigned long CurrentSize;
 250
 251    /** \brief The total number of bytes to be downloaded.  Zero if the
 252     *  total size of the final is unknown.
 253     */
 254    unsigned long TotalSize;
 255
 256    /** \brief How much of the file was already downloaded prior to
 257     *  starting this worker.
 258     */
 259    unsigned long ResumePoint;
 260
 261    /** \brief Tell the subprocess to download the given item.
 262     *
 263     *  \param Item the item to queue up.
 264     *  \return \b true if the item was successfully enqueued.
 265     *
 266     *  Queues up a 600 URI Acquire message for the given item to be
 267     *  sent at the next possible moment.  Does \e not flush the output
 268     *  queue.
 269     */
 270    bool QueueItem(pkgAcquire::Queue::QItem *Item);
 271
 272    /** \brief Start up the worker and fill in #Config.
 273     *
 274     *  Reads the first message from the worker, which is assumed to be
 275     *  a 100 Capabilities message.
 276     *
 277     *  \return \b true if all operations completed successfully.
 278     */
 279    bool Start();
 280
 281    /** \brief Update the worker statistics (CurrentSize, TotalSize,
 282     *  etc).
 283     */
 284    void Pulse();
 285
 286    /** \return The fetch method configuration. */
 287    inline const MethodConfig *GetConf() const {return Config;};
 288
 289    /** \brief Create a new Worker to download files.
 290     *
 291     *  \param OwnerQ The queue into which this worker should be
 292     *  placed.
 293     *
 294     *  \param Config A location in which to store information about
 295     *  the fetch method.
 296     *
 297     *  \param Log The download progress indicator that should be used
 298     *  to report the progress of this worker.
 299     */
 300    Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log);
 301
 302    /** \brief Create a new Worker that should just retrieve
 303     *  information about the fetch method.
 304     *
 305     *  Nothing in particular forces you to refrain from actually
 306     *  downloading stuff, but the various status callbacks won't be
 307     *  invoked.
 308     *
 309     *  \param Config A location in which to store information about
 310     *  the fetch method.
 311     */
 312    Worker(MethodConfig *Config);
 313
 314    /** \brief Clean up this worker.
 315     *
 316     *  Closes the file descriptors; if MethodConfig::NeedsCleanup is
 317     *  \b false, also rudely interrupts the worker with a SIGINT.
 318     */
 319    ~Worker();
 320 };
 321
 322 /** @} */
 323
 324 #endif