[ABI-Break] remove the PACKAGE_MATCHER_ABI_COMPAT defines
[apt.git] / apt-pkg / acquire-worker.h
CommitLineData
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 45class 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