2 Unix SMB/CIFS implementation.
3 Infrastructure for async requests
4 Copyright (C) Volker Lendecke 2008
5 Copyright (C) Stefan Metzmacher 2009
7 ** NOTE! The following LGPL license applies to the tevent
8 ** library. This does NOT imply that all of Samba is released
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.
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.
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/>.
27 #include "tevent_internal.h"
28 #include "tevent_util.h"
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
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
41 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
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,
48 (unsigned long long)req->internal.error,
49 (unsigned long long)req->internal.error,
50 talloc_get_name(req->data),
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
62 * This function should be used by callers of the async API
65 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req)
67 if (!req->private_print) {
68 return tevent_req_default_print(req, mem_ctx);
71 return req->private_print(req, mem_ctx);
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
80 * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS
83 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
89 struct tevent_req *req;
90 void **ppdata = (void **)pdata;
93 req = talloc_zero(mem_ctx, struct tevent_req);
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) {
107 data = talloc_size(req, data_size);
112 memset(data, '\0', data_size);
113 talloc_set_name_const(data, type);
121 void _tevent_req_notify_callback(struct tevent_req *req, const char *location)
123 req->internal.finish_location = location;
124 if (req->async.fn != NULL) {
129 static void tevent_req_finish(struct tevent_req *req,
130 enum tevent_req_state state,
131 const char *location)
133 req->internal.state = state;
134 _tevent_req_notify_callback(req, location);
138 * @brief An async request has successfully finished
139 * @param[in] req The finished request
141 * tevent_req_done is to be used by implementors of async requests. When a
142 * request is successfully finished, this function calls the user's completion
146 void _tevent_req_done(struct tevent_req *req,
147 const char *location)
149 tevent_req_finish(req, TEVENT_REQ_DONE, location);
153 * @brief An async request has seen an error
154 * @param[in] req The request with an error
155 * @param[in] error The error code
157 * tevent_req_done is to be used by implementors of async requests. When a
158 * request can not successfully completed, the implementation should call this
159 * function with the appropriate status code.
161 * If error is 0 the function returns false and does nothing more.
163 * Call pattern would be
165 * int error = first_function();
166 * if (tevent_req_error(req, error)) {
170 * error = second_function();
171 * if (tevent_req_error(req, error)) {
175 * tevent_req_done(req);
180 bool _tevent_req_error(struct tevent_req *req,
182 const char *location)
188 req->internal.error = error;
189 tevent_req_finish(req, TEVENT_REQ_USER_ERROR, location);
194 * @brief Helper function for nomem check
195 * @param[in] p The pointer to be checked
196 * @param[in] req The request being processed
198 * Convenience helper to easily check alloc failure within a callback
199 * implementing the next step of an async request.
201 * Call pattern would be
203 * p = talloc(mem_ctx, bla);
204 * if (tevent_req_nomem(p, req)) {
210 bool _tevent_req_nomem(const void *p,
211 struct tevent_req *req,
212 const char *location)
217 tevent_req_finish(req, TEVENT_REQ_NO_MEMORY, location);
222 * @brief Immediate event callback
223 * @param[in] ev Event context
224 * @param[in] im The immediate event
225 * @param[in] priv The async request to be finished
227 static void tevent_req_trigger(struct tevent_context *ev,
228 struct tevent_immediate *im,
231 struct tevent_req *req = talloc_get_type(private_data,
234 tevent_req_finish(req, req->internal.state,
235 req->internal.finish_location);
239 * @brief Finish a request before the caller had the change to set the callback
240 * @param[in] req The finished request
241 * @param[in] ev The tevent_context for the timed event
242 * @retval req will be returned
244 * An implementation of an async request might find that it can either finish
245 * the request without waiting for an external event, or it can't even start
246 * the engine. To present the illusion of a callback to the user of the API,
247 * the implementation can call this helper function which triggers an
248 * immediate timed event. This way the caller can use the same calling
249 * conventions, independent of whether the request was actually deferred.
252 struct tevent_req *tevent_req_post(struct tevent_req *req,
253 struct tevent_context *ev)
255 tevent_schedule_immediate(req->internal.trigger,
256 ev, tevent_req_trigger, req);
260 bool tevent_req_is_in_progress(struct tevent_req *req)
262 if (req->internal.state == TEVENT_REQ_IN_PROGRESS) {
270 * @brief This function destroys the attached private data
271 * @param[in] req The finished request
273 * This function can be called as last action of a _recv()
274 * function, it destroys the data attached to the tevent_req.
276 void tevent_req_received(struct tevent_req *req)
278 TALLOC_FREE(req->data);
279 req->private_print = NULL;
281 TALLOC_FREE(req->internal.trigger);
282 TALLOC_FREE(req->internal.timer);
284 req->internal.state = TEVENT_REQ_RECEIVED;
287 bool tevent_req_poll(struct tevent_req *req,
288 struct tevent_context *ev)
290 while (tevent_req_is_in_progress(req)) {
293 ret = tevent_loop_once(ev);
302 bool tevent_req_is_error(struct tevent_req *req, enum tevent_req_state *state,
305 if (req->internal.state == TEVENT_REQ_DONE) {
308 if (req->internal.state == TEVENT_REQ_USER_ERROR) {
309 *error = req->internal.error;
311 *state = req->internal.state;
315 static void tevent_req_timedout(struct tevent_context *ev,
316 struct tevent_timer *te,
320 struct tevent_req *req = talloc_get_type(private_data,
323 TALLOC_FREE(req->internal.timer);
325 tevent_req_finish(req, TEVENT_REQ_TIMED_OUT, __FUNCTION__);
328 bool tevent_req_set_endtime(struct tevent_req *req,
329 struct tevent_context *ev,
330 struct timeval endtime)
332 TALLOC_FREE(req->internal.timer);
334 req->internal.timer = tevent_add_timer(ev, req, endtime,
337 if (tevent_req_nomem(req->internal.timer, req)) {
344 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt)
347 req->async.private_data = pvt;
350 void *_tevent_req_callback_data(struct tevent_req *req)
352 return req->async.private_data;
355 void *_tevent_req_data(struct tevent_req *req)
360 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn)
362 req->private_print = fn;