Add tevent_req_notify_callback
[ira/wip.git] / lib / tevent / tevent_req.c
1 /*
2    Unix SMB/CIFS implementation.
3    Infrastructure for async requests
4    Copyright (C) Volker Lendecke 2008
5    Copyright (C) Stefan Metzmacher 2009
6
7      ** NOTE! The following LGPL license applies to the tevent
8      ** library. This does NOT imply that all of Samba is released
9      ** under the LGPL
10
11    This library is free software; you can redistribute it and/or
12    modify it under the terms of the GNU Lesser General Public
13    License as published by the Free Software Foundation; either
14    version 3 of the License, or (at your option) any later version.
15
16    This library is distributed in the hope that it will be useful,
17    but WITHOUT ANY WARRANTY; without even the implied warranty of
18    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
19    Lesser General Public License for more details.
20
21    You should have received a copy of the GNU Lesser General Public
22    License along with this library; if not, see <http://www.gnu.org/licenses/>.
23 */
24
25 #include "replace.h"
26 #include "tevent.h"
27 #include "tevent_internal.h"
28 #include "tevent_util.h"
29
30 /**
31  * @brief The default print function for creating debug messages
32  * @param[in] req       The request to be printed
33  * @param[in] mem_ctx   The memory context for the result
34  * @retval              Text representation of req
35  *
36  * The function should not be used by users of the asynx API,
37  * but custom print function can use it and append custom text
38  * to the string.
39  */
40
41 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
42 {
43         return talloc_asprintf(mem_ctx,
44                                "tevent_req[%p/%s]: state[%d] error[%lld (0x%llX)] "
45                                " state[%s (%p)] timer[%p]",
46                                req, req->internal.create_location,
47                                req->internal.state,
48                                (unsigned long long)req->internal.error,
49                                (unsigned long long)req->internal.error,
50                                talloc_get_name(req->data),
51                                req->data,
52                                req->internal.timer
53                                );
54 }
55
56 /**
57  * @brief Print an tevent_req structure in debug messages
58  * @param[in] mem_ctx   The memory context for the result
59  * @param[in] req       The request to be printed
60  * @retval              Text representation of req
61  *
62  * This function should be used by callers of the async API
63  */
64
65 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req)
66 {
67         if (!req->private_print) {
68                 return tevent_req_default_print(req, mem_ctx);
69         }
70
71         return req->private_print(req, mem_ctx);
72 }
73
74 /**
75  * @brief Create an async request
76  * @param[in] mem_ctx   The memory context for the result
77  * @param[in] ev        The event context this async request will be driven by
78  * @retval              A new async request
79  *
80  * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS
81  */
82
83 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
84                                     void *pdata,
85                                     size_t data_size,
86                                     const char *type,
87                                     const char *location)
88 {
89         struct tevent_req *req;
90         void **ppdata = (void **)pdata;
91         void *data;
92
93         req = talloc_zero(mem_ctx, struct tevent_req);
94         if (req == NULL) {
95                 return NULL;
96         }
97         req->internal.private_type      = type;
98         req->internal.create_location   = location;
99         req->internal.finish_location   = NULL;
100         req->internal.state             = TEVENT_REQ_IN_PROGRESS;
101         req->internal.trigger           = tevent_create_immediate(req);
102         if (!req->internal.trigger) {
103                 talloc_free(req);
104                 return NULL;
105         }
106
107         data = talloc_size(req, data_size);
108         if (data == NULL) {
109                 talloc_free(req);
110                 return NULL;
111         }
112         talloc_set_name_const(data, type);
113
114         req->data = data;
115
116         *ppdata = data;
117         return req;
118 }
119
120 void _tevent_req_notify_callback(struct tevent_req *req, const char *location)
121 {
122         req->internal.finish_location = location;
123         if (req->async.fn != NULL) {
124                 req->async.fn(req);
125         }
126 }
127
128 static void tevent_req_finish(struct tevent_req *req,
129                               enum tevent_req_state state,
130                               const char *location)
131 {
132         req->internal.state = state;
133         _tevent_req_notify_callback(req, location);
134 }
135
136 /**
137  * @brief An async request has successfully finished
138  * @param[in] req       The finished request
139  *
140  * tevent_req_done is to be used by implementors of async requests. When a
141  * request is successfully finished, this function calls the user's completion
142  * function.
143  */
144
145 void _tevent_req_done(struct tevent_req *req,
146                       const char *location)
147 {
148         tevent_req_finish(req, TEVENT_REQ_DONE, location);
149 }
150
151 /**
152  * @brief An async request has seen an error
153  * @param[in] req       The request with an error
154  * @param[in] error     The error code
155  *
156  * tevent_req_done is to be used by implementors of async requests. When a
157  * request can not successfully completed, the implementation should call this
158  * function with the appropriate status code.
159  *
160  * If error is 0 the function returns false and does nothing more.
161  *
162  * Call pattern would be
163  * \code
164  * int error = first_function();
165  * if (tevent_req_error(req, error)) {
166  *      return;
167  * }
168  *
169  * error = second_function();
170  * if (tevent_req_error(req, error)) {
171  *      return;
172  * }
173  *
174  * tevent_req_done(req);
175  * return;
176  * \endcode
177  */
178
179 bool _tevent_req_error(struct tevent_req *req,
180                        uint64_t error,
181                        const char *location)
182 {
183         if (error == 0) {
184                 return false;
185         }
186
187         req->internal.error = error;
188         tevent_req_finish(req, TEVENT_REQ_USER_ERROR, location);
189         return true;
190 }
191
192 /**
193  * @brief Helper function for nomem check
194  * @param[in] p         The pointer to be checked
195  * @param[in] req       The request being processed
196  *
197  * Convenience helper to easily check alloc failure within a callback
198  * implementing the next step of an async request.
199  *
200  * Call pattern would be
201  * \code
202  * p = talloc(mem_ctx, bla);
203  * if (tevent_req_nomem(p, req)) {
204  *      return;
205  * }
206  * \endcode
207  */
208
209 bool _tevent_req_nomem(const void *p,
210                        struct tevent_req *req,
211                        const char *location)
212 {
213         if (p != NULL) {
214                 return false;
215         }
216         tevent_req_finish(req, TEVENT_REQ_NO_MEMORY, location);
217         return true;
218 }
219
220 /**
221  * @brief Immediate event callback
222  * @param[in] ev        Event context
223  * @param[in] im        The immediate event
224  * @param[in] priv      The async request to be finished
225  */
226 static void tevent_req_trigger(struct tevent_context *ev,
227                                struct tevent_immediate *im,
228                                void *private_data)
229 {
230         struct tevent_req *req = talloc_get_type(private_data,
231                                  struct tevent_req);
232
233         tevent_req_finish(req, req->internal.state,
234                           req->internal.finish_location);
235 }
236
237 /**
238  * @brief Finish a request before the caller had the change to set the callback
239  * @param[in] req       The finished request
240  * @param[in] ev        The tevent_context for the timed event
241  * @retval              req will be returned
242  *
243  * An implementation of an async request might find that it can either finish
244  * the request without waiting for an external event, or it can't even start
245  * the engine. To present the illusion of a callback to the user of the API,
246  * the implementation can call this helper function which triggers an
247  * immediate timed event. This way the caller can use the same calling
248  * conventions, independent of whether the request was actually deferred.
249  */
250
251 struct tevent_req *tevent_req_post(struct tevent_req *req,
252                                    struct tevent_context *ev)
253 {
254         tevent_schedule_immediate(req->internal.trigger,
255                                   ev, tevent_req_trigger, req);
256         return req;
257 }
258
259 bool tevent_req_is_in_progress(struct tevent_req *req)
260 {
261         if (req->internal.state == TEVENT_REQ_IN_PROGRESS) {
262                 return true;
263         }
264
265         return false;
266 }
267
268 /**
269  * @brief This function destroys the attached private data
270  * @param[in] req       The finished request
271  *
272  * This function can be called as last action of a _recv()
273  * function, it destroys the data attached to the tevent_req.
274  */
275 void tevent_req_received(struct tevent_req *req)
276 {
277         TALLOC_FREE(req->data);
278         req->private_print = NULL;
279
280         TALLOC_FREE(req->internal.trigger);
281         TALLOC_FREE(req->internal.timer);
282
283         req->internal.state = TEVENT_REQ_RECEIVED;
284 }
285
286 bool tevent_req_poll(struct tevent_req *req,
287                      struct tevent_context *ev)
288 {
289         while (tevent_req_is_in_progress(req)) {
290                 int ret;
291
292                 ret = tevent_loop_once(ev);
293                 if (ret != 0) {
294                         return false;
295                 }
296         }
297
298         return true;
299 }
300
301 bool tevent_req_is_error(struct tevent_req *req, enum tevent_req_state *state,
302                         uint64_t *error)
303 {
304         if (req->internal.state == TEVENT_REQ_DONE) {
305                 return false;
306         }
307         if (req->internal.state == TEVENT_REQ_USER_ERROR) {
308                 *error = req->internal.error;
309         }
310         *state = req->internal.state;
311         return true;
312 }
313
314 static void tevent_req_timedout(struct tevent_context *ev,
315                                struct tevent_timer *te,
316                                struct timeval now,
317                                void *private_data)
318 {
319         struct tevent_req *req = talloc_get_type(private_data,
320                                  struct tevent_req);
321
322         TALLOC_FREE(req->internal.timer);
323
324         tevent_req_finish(req, TEVENT_REQ_TIMED_OUT, __FUNCTION__);
325 }
326
327 bool tevent_req_set_endtime(struct tevent_req *req,
328                             struct tevent_context *ev,
329                             struct timeval endtime)
330 {
331         TALLOC_FREE(req->internal.timer);
332
333         req->internal.timer = tevent_add_timer(ev, req, endtime,
334                                                tevent_req_timedout,
335                                                req);
336         if (tevent_req_nomem(req->internal.timer, req)) {
337                 return false;
338         }
339
340         return true;
341 }
342
343 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt)
344 {
345         req->async.fn = fn;
346         req->async.private_data = pvt;
347 }
348
349 void *_tevent_req_callback_data(struct tevent_req *req)
350 {
351         return req->async.private_data;
352 }
353
354 void *_tevent_req_data(struct tevent_req *req)
355 {
356         return req->data;
357 }
358
359 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn)
360 {
361         req->private_print = fn;
362 }