apt-pkg/acquire-worker.h

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