apt  2.2.4
About: Apt (Advanced Package Tool) is a management system for software packages (Debian/Ubuntu). Release series 2.2.
  Fossies Dox: apt-2.2.4.tar.gz  ("unofficial" and yet experimental doxygen-generated source code documentation)  

acquire-worker.h
Go to the documentation of this file.
1 // -*- mode: cpp; mode: fold -*-
2 // Description /*{{{*/
3 /* ######################################################################
4 
5  Acquire Worker - Worker process manager
6 
7  Each worker class is associated with exactly 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 <string>
25 #include <vector>
26 #include <sys/types.h>
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 APT_PUBLIC 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  */
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  */
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  */
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  */
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 Tell the subprocess to download the given item.
255  *
256  * \param Item the item to queue up.
257  * \return \b true if the item was successfully enqueued.
258  *
259  * Queues up a 600 URI Acquire message for the given item to be
260  * sent at the next possible moment. Does \e not flush the output
261  * queue.
262  */
263  bool QueueItem(pkgAcquire::Queue::QItem *Item);
264  APT_HIDDEN bool ReplyAux(pkgAcquire::ItemDesc const &Item);
265 
266  /** \brief Start up the worker and fill in #Config.
267  *
268  * Reads the first message from the worker, which is assumed to be
269  * a 100 Capabilities message.
270  *
271  * \return \b true if all operations completed successfully.
272  */
273  bool Start();
274 
275  /** \brief Update the worker statistics (CurrentSize, TotalSize,
276  * etc).
277  */
278  void Pulse();
279 
280  /** \return The fetch method configuration. */
281  inline const MethodConfig *GetConf() const {return Config;};
282 
283  /** \brief Create a new Worker to download files.
284  *
285  * \param OwnerQ The queue into which this worker should be
286  * placed.
287  *
288  * \param Config A location in which to store information about
289  * the fetch method.
290  *
291  * \param Log The download progress indicator that should be used
292  * to report the progress of this worker.
293  */
294  Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log);
295 
296  /** \brief Create a new Worker that should just retrieve
297  * information about the fetch method.
298  *
299  * Nothing in particular forces you to refrain from actually
300  * downloading stuff, but the various status callbacks won't be
301  * invoked.
302  *
303  * \param Config A location in which to store information about
304  * the fetch method.
305  */
306  explicit Worker(MethodConfig *Config);
307 
308  /** \brief Clean up this worker.
309  *
310  * Closes the file descriptors; if MethodConfig::NeedsCleanup is
311  * \b false, also rudely interrupts the worker with a SIGINT.
312  */
313  virtual ~Worker();
314 
315 private:
316  APT_HIDDEN void PrepareFiles(char const * const caller, pkgAcquire::Queue::QItem const * const Itm);
317  APT_HIDDEN void HandleFailure(std::vector<pkgAcquire::Item *> const &ItmOwners,
318  pkgAcquire::MethodConfig *const Config, pkgAcquireStatus *const Log,
319  std::string const &Message, bool const errTransient, bool const errAuthErr);
320 };
321 
322 /** @} */
323 
324 #endif
A monitor object for downloads controlled by the pkgAcquire class. {{{.
Definition: acquire.h:696
Represents the process by which a pkgAcquire object should retrieve a file or a collection of files.
Definition: acquire-item.h:59
std::string Access
The access method to be used by this worker.
bool OutReady
Set to true if the worker is in a state in which it is legal to send commands to it.
bool ReadMessages()
Retrieve any available messages from the subprocess.
bool RunMessages()
Parse and dispatch pending messages.
std::string OutQueue
Buffers pending writes to the subprocess.
MethodConfig()
Set up the default method parameters.
bool OutFdReady()
Send any pending commands to the subprocess.
int InFd
A file descriptor connected to the standard output of the subprocess.
int PrivSepSocketFdChild
MethodConfig * Config
The configuration of this method. On startup, the target of this pointer is filled in with basic data...
bool QueueItem(pkgAcquire::Queue::QItem *Item)
Tell the subprocess to download the given item.
Worker * NextAcquire
The next link on the Acquire list.
APT_HIDDEN void PrepareFiles(char const *const caller, pkgAcquire::Queue::QItem const *const Itm)
APT_HIDDEN void HandleFailure(std::vector< pkgAcquire::Item * > const &ItmOwners, pkgAcquire::MethodConfig *const Config, pkgAcquireStatus *const Log, std::string const &Message, bool const errTransient, bool const errAuthErr)
pid_t Process
The PID of the subprocess.
bool InFdReady()
Read and dispatch any pending messages from the subprocess.
bool MediaChange(std::string Message)
Handle a 403 Media Change message.
void ItemDone()
Invoked when a fetch job is completed, either successfully or unsuccessfully.
Worker * NextQueue
The next link on the Queue list.
pkgAcquireStatus * Log
The download progress indicator to which progress messages should be sent.
bool InReady
Set to true if the worker is in a state in which it might generate data or command responses.
const MethodConfig * GetConf() const
bool MethodFailure()
Invoked when the worked process dies unexpectedly.
Queue * OwnerQ
The Queue with which this worker is associated.
void Construct()
Common code for the constructor.
APT_HIDDEN bool ReplyAux(pkgAcquire::ItemDesc const &Item)
bool Capabilities(std::string Message)
Handle a 100 Capabilities response from the subprocess.
bool Start()
Start up the worker and fill in Config.
Worker(Queue *OwnerQ, MethodConfig *Config, pkgAcquireStatus *Log)
Create a new Worker to download files.
std::vector< std::string > MessageQueue
The raw text values of messages received from the worker, in sequence.
int PrivSepSocketFd
The socket to send SCM_RIGHTS message through.
pkgAcquire::Queue::QItem * CurrentItem
The queue entry that is currently being downloaded.
void *const d
dpointer placeholder (for later in case we need it)
std::string Status
The most recent status string received from the subprocess.
Worker(MethodConfig *Config)
Create a new Worker that should just retrieve information about the fetch method.
virtual ~Worker()
Clean up this worker.
void Pulse()
Update the worker statistics (CurrentSize, TotalSize, etc).
int OutFd
A file descriptor connected to the standard input of the subprocess.
bool SendConfiguration()
Send a 601 Configuration message (containing the APT configuration) to the subprocess.
#define APT_PUBLIC
Definition: macros.h:77
#define APT_HIDDEN
Definition: macros.h:78