Commit | Line | Data |
---|---|---|
0118833a AL |
1 | // -*- mode: cpp; mode: fold -*- |
2 | // Description /*{{{*/ | |
b2e465d6 | 3 | // $Id: acquire-worker.h,v 1.12 2001/02/20 07:03:17 jgg Exp $ |
0118833a AL |
4 | /* ###################################################################### |
5 | ||
6 | Acquire Worker - Worker process manager | |
7 | ||
3b5421b4 AL |
8 | Each worker class is associated with exaclty one subprocess. |
9 | ||
0118833a AL |
10 | ##################################################################### */ |
11 | /*}}}*/ | |
3174e150 MV |
12 | |
13 | /** \addtogroup acquire | |
14 | * @{ | |
15 | * | |
16 | * \file acquire-worker.h | |
17 | */ | |
18 | ||
0118833a AL |
19 | #ifndef PKGLIB_ACQUIRE_WORKER_H |
20 | #define PKGLIB_ACQUIRE_WORKER_H | |
21 | ||
22 | #include <apt-pkg/acquire.h> | |
229fb1a3 | 23 | #include <apt-pkg/weakptr.h> |
0118833a | 24 | |
0118833a | 25 | |
3174e150 MV |
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 | */ | |
229fb1a3 | 45 | class pkgAcquire::Worker : public WeakPointable |
0118833a | 46 | { |
be9b62f7 MV |
47 | /** \brief dpointer placeholder (for later in case we need it) */ |
48 | void *d; | |
49 | ||
b2e465d6 | 50 | friend class pkgAcquire; |
0a8a80e5 | 51 | |
0118833a | 52 | protected: |
b2e465d6 | 53 | friend class Queue; |
3b5421b4 | 54 | |
3174e150 MV |
55 | /** \brief The next link on the Queue list. |
56 | * | |
57 | * \todo This is always NULL; is it just for future use? | |
58 | */ | |
0a8a80e5 | 59 | Worker *NextQueue; |
3174e150 MV |
60 | |
61 | /** \brief The next link on the Acquire list. */ | |
0a8a80e5 | 62 | Worker *NextAcquire; |
0118833a | 63 | |
3174e150 | 64 | /** \brief The Queue with which this worker is associated. */ |
0118833a | 65 | Queue *OwnerQ; |
3174e150 MV |
66 | |
67 | /** \brief The download progress indicator to which progress | |
68 | * messages should be sent. | |
69 | */ | |
8267fe24 | 70 | pkgAcquireStatus *Log; |
3174e150 MV |
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 | */ | |
3b5421b4 | 76 | MethodConfig *Config; |
3174e150 MV |
77 | |
78 | /** \brief The access method to be used by this worker. | |
79 | * | |
80 | * \todo Doesn't this duplicate Config->Access? | |
81 | */ | |
8f3ba4e8 | 82 | std::string Access; |
c46824ce | 83 | |
3174e150 | 84 | /** \brief The PID of the subprocess. */ |
3b5421b4 | 85 | pid_t Process; |
3174e150 MV |
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 | */ | |
3b5421b4 | 92 | int InFd; |
3174e150 MV |
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 | */ | |
3b5421b4 | 99 | int OutFd; |
3174e150 MV |
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 | */ | |
0a8a80e5 | 106 | bool InReady; |
3174e150 MV |
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 | */ | |
0a8a80e5 | 113 | bool OutReady; |
0118833a | 114 | |
3174e150 | 115 | /** If \b true, debugging output will be sent to std::clog. */ |
3b5421b4 | 116 | bool Debug; |
3174e150 MV |
117 | |
118 | /** \brief The raw text values of messages received from the | |
119 | * worker, in sequence. | |
120 | */ | |
8f3ba4e8 | 121 | std::vector<std::string> MessageQueue; |
3174e150 MV |
122 | |
123 | /** \brief Buffers pending writes to the subprocess. | |
124 | * | |
125 | * \todo Wouldn't a std::dequeue be more appropriate? | |
126 | */ | |
8f3ba4e8 | 127 | std::string OutQueue; |
0a8a80e5 | 128 | |
3174e150 MV |
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 | */ | |
3b5421b4 AL |
135 | void Construct(); |
136 | ||
3174e150 MV |
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 | */ | |
3b5421b4 | 147 | bool ReadMessages(); |
3174e150 MV |
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 | */ | |
3b5421b4 | 158 | bool RunMessages(); |
3174e150 MV |
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 | */ | |
0a8a80e5 | 166 | bool InFdReady(); |
3174e150 MV |
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 | */ | |
0a8a80e5 | 175 | bool OutFdReady(); |
3b5421b4 | 176 | |
3174e150 MV |
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 | */ | |
8f3ba4e8 | 186 | bool Capabilities(std::string Message); |
3174e150 MV |
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 | */ | |
0a8a80e5 | 204 | bool SendConfiguration(); |
3174e150 MV |
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 | */ | |
8f3ba4e8 | 217 | bool MediaChange(std::string Message); |
542ec555 | 218 | |
3174e150 MV |
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 | */ | |
0a8a80e5 | 228 | bool MethodFailure(); |
3174e150 MV |
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 | */ | |
8267fe24 | 235 | void ItemDone(); |
0118833a AL |
236 | |
237 | public: | |
238 | ||
3174e150 | 239 | /** \brief The queue entry that is currently being downloaded. */ |
0a8a80e5 | 240 | pkgAcquire::Queue::QItem *CurrentItem; |
3174e150 MV |
241 | |
242 | /** \brief The most recent status string received from the | |
243 | * subprocess. | |
244 | */ | |
8f3ba4e8 | 245 | std::string Status; |
3174e150 MV |
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 | */ | |
73da43e9 | 250 | unsigned long long CurrentSize; |
3174e150 MV |
251 | |
252 | /** \brief The total number of bytes to be downloaded. Zero if the | |
253 | * total size of the final is unknown. | |
254 | */ | |
73da43e9 | 255 | unsigned long long TotalSize; |
3174e150 MV |
256 | |
257 | /** \brief How much of the file was already downloaded prior to | |
258 | * starting this worker. | |
259 | */ | |
73da43e9 | 260 | unsigned long long ResumePoint; |
8b75eb1c | 261 | |
3174e150 MV |
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 | */ | |
0a8a80e5 | 271 | bool QueueItem(pkgAcquire::Queue::QItem *Item); |
3174e150 MV |
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 | */ | |
8267fe24 | 280 | bool Start(); |
3174e150 MV |
281 | |
282 | /** \brief Update the worker statistics (CurrentSize, TotalSize, | |
283 | * etc). | |
284 | */ | |
8267fe24 | 285 | void Pulse(); |
3174e150 MV |
286 | |
287 | /** \return The fetch method configuration. */ | |
8e5fc8f5 | 288 | inline const MethodConfig *GetConf() const {return Config;}; |
3174e150 MV |
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 | */ | |
8267fe24 | 301 | Worker(Queue *OwnerQ,MethodConfig *Config,pkgAcquireStatus *Log); |
3174e150 MV |
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 | */ | |
0118833a | 313 | Worker(MethodConfig *Config); |
3174e150 MV |
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 | */ | |
be9b62f7 | 320 | virtual ~Worker(); |
0118833a AL |
321 | }; |
322 | ||
3174e150 MV |
323 | /** @} */ |
324 | ||
0118833a | 325 | #endif |