2 Unix SMB/CIFS implementation.
3 Infrastructure for async requests
4 Copyright (C) Volker Lendecke 2008
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 3 of the License, or
9 (at your option) any later version.
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>.
21 #include "lib/tevent/tevent.h"
22 #include "lib/talloc/talloc.h"
23 #include "lib/util/dlinklist.h"
24 #include "lib/async_req/async_req.h"
27 #define TALLOC_FREE(ctx) do { talloc_free(ctx); ctx=NULL; } while(0)
31 * @brief Print an async_req structure
32 * @param[in] mem_ctx The memory context for the result
33 * @param[in] req The request to be printed
34 * @retval Text representation of req
36 * This is a default print function for async requests. Implementations should
37 * override this with more specific information.
39 * This function should not be used by async API users, this is non-static
40 * only to allow implementations to easily provide default information in
41 * their specific functions.
44 char *async_req_print(TALLOC_CTX *mem_ctx, struct async_req *req)
46 return talloc_asprintf(mem_ctx, "async_req: state=%d, status=%s, "
47 "priv=%s", req->state, nt_errstr(req->status),
48 talloc_get_name(req->private_data));
52 * @brief Create an async request
53 * @param[in] mem_ctx The memory context for the result
54 * @param[in] ev The event context this async request will be driven by
55 * @retval A new async request
57 * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS
60 struct async_req *async_req_new(TALLOC_CTX *mem_ctx)
62 struct async_req *result;
64 result = talloc_zero(mem_ctx, struct async_req);
68 result->state = ASYNC_REQ_IN_PROGRESS;
69 result->print = async_req_print;
74 * @brief An async request has successfully finished
75 * @param[in] req The finished request
77 * async_req_done is to be used by implementors of async requests. When a
78 * request is successfully finished, this function calls the user's completion
82 void async_req_done(struct async_req *req)
84 req->status = NT_STATUS_OK;
85 req->state = ASYNC_REQ_DONE;
86 if (req->async.fn != NULL) {
92 * @brief An async request has seen an error
93 * @param[in] req The request with an error
94 * @param[in] status The error code
96 * async_req_done is to be used by implementors of async requests. When a
97 * request can not successfully completed, the implementation should call this
98 * function with the appropriate status code.
101 void async_req_error(struct async_req *req, NTSTATUS status)
103 req->status = status;
104 req->state = ASYNC_REQ_ERROR;
105 if (req->async.fn != NULL) {
111 * @brief Timed event callback
112 * @param[in] ev Event context
113 * @param[in] te The timed event
114 * @param[in] now zero time
115 * @param[in] priv The async request to be finished
118 static void async_trigger(struct tevent_context *ev, struct tevent_timer *te,
119 struct timeval now, void *priv)
121 struct async_req *req = talloc_get_type_abort(priv, struct async_req);
124 if (NT_STATUS_IS_OK(req->status)) {
128 async_req_error(req, req->status);
133 * @brief Finish a request before it started processing
134 * @param[in] req The finished request
135 * @param[in] status The success code
137 * An implementation of an async request might find that it can either finish
138 * the request without waiting for an external event, or it can't even start
139 * the engine. To present the illusion of a callback to the user of the API,
140 * the implementation can call this helper function which triggers an
141 * immediate timed event. This way the caller can use the same calling
142 * conventions, independent of whether the request was actually deferred.
145 bool async_post_status(struct async_req *req, struct tevent_context *ev,
148 req->status = status;
150 if (tevent_add_timer(ev, req, timeval_zero(),
151 async_trigger, req) == NULL) {
158 * @brief Helper function for nomem check
159 * @param[in] p The pointer to be checked
160 * @param[in] req The request being processed
162 * Convenience helper to easily check alloc failure within a callback
163 * implementing the next step of an async request.
165 * Call pattern would be
167 * p = talloc(mem_ctx, bla);
168 * if (async_req_nomem(p, req)) {
174 bool async_req_nomem(const void *p, struct async_req *req)
179 async_req_error(req, NT_STATUS_NO_MEMORY);
183 bool async_req_is_error(struct async_req *req, NTSTATUS *status)
185 if (req->state < ASYNC_REQ_DONE) {
186 *status = NT_STATUS_INTERNAL_ERROR;
189 if (req->state == ASYNC_REQ_ERROR) {
190 *status = req->status;
196 NTSTATUS async_req_simple_recv(struct async_req *req)
200 if (async_req_is_error(req, &status)) {
206 static void async_req_timedout(struct tevent_context *ev,
207 struct tevent_timer *te,
211 struct async_req *req = talloc_get_type_abort(
212 priv, struct async_req);
214 async_req_error(req, NT_STATUS_IO_TIMEOUT);
217 bool async_req_set_timeout(struct async_req *req, struct tevent_context *ev,
220 return (tevent_add_timer(ev, req,
221 timeval_current_ofs(to.tv_sec, to.tv_usec),
222 async_req_timedout, req)
226 struct async_req *async_wait_send(TALLOC_CTX *mem_ctx,
227 struct tevent_context *ev,
230 struct async_req *result;
232 result = async_req_new(mem_ctx);
233 if (result == NULL) {
236 if (!async_req_set_timeout(result, ev, to)) {
243 NTSTATUS async_wait_recv(struct async_req *req)
248 struct async_queue_entry {
249 struct async_queue_entry *prev, *next;
250 struct async_req_queue *queue;
251 struct async_req *req;
252 void (*trigger)(struct async_req *req);
255 struct async_req_queue {
256 struct async_queue_entry *queue;
259 struct async_req_queue *async_req_queue_init(TALLOC_CTX *mem_ctx)
261 return talloc_zero(mem_ctx, struct async_req_queue);
264 static int async_queue_entry_destructor(struct async_queue_entry *e)
266 struct async_req_queue *queue = e->queue;
268 DLIST_REMOVE(queue->queue, e);
270 if (queue->queue != NULL) {
271 queue->queue->trigger(queue->queue->req);
277 static void async_req_immediate_trigger(struct tevent_context *ev,
278 struct tevent_timer *te,
282 struct async_queue_entry *e = talloc_get_type_abort(
283 priv, struct async_queue_entry);
289 bool async_req_enqueue(struct async_req_queue *queue, struct tevent_context *ev,
290 struct async_req *req,
291 void (*trigger)(struct async_req *req))
293 struct async_queue_entry *e;
296 busy = (queue->queue != NULL);
298 e = talloc(req, struct async_queue_entry);
304 e->trigger = trigger;
307 DLIST_ADD_END(queue->queue, e, struct async_queue_entry *);
308 talloc_set_destructor(e, async_queue_entry_destructor);
311 struct tevent_timer *te;
313 te = tevent_add_timer(ev, e, timeval_zero(),
314 async_req_immediate_trigger,
325 bool _async_req_setup(TALLOC_CTX *mem_ctx, struct async_req **preq,
326 void *pstate, size_t state_size, const char *typename)
328 struct async_req *req;
329 void **ppstate = (void **)pstate;
332 req = async_req_new(mem_ctx);
336 state = talloc_size(req, state_size);
341 talloc_set_name_const(state, typename);
342 req->private_data = state;