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