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/>.
23 * @brief Print an async_req structure
24 * @param[in] mem_ctx The memory context for the result
25 * @param[in] req The request to be printed
26 * @retval Text representation of req
28 * This is a default print function for async requests. Implementations should
29 * override this with more specific information.
31 * This function should not be used by async API users, this is non-static
32 * only to allow implementations to easily provide default information in
33 * their specific functions.
36 char *async_req_print(TALLOC_CTX *mem_ctx, struct async_req *req)
38 return talloc_asprintf(mem_ctx, "async_req: state=%d, status=%s, "
39 "priv=%s", req->state, nt_errstr(req->status),
40 talloc_get_name(req->private_data));
44 * @brief Create an async request
45 * @param[in] mem_ctx The memory context for the result
46 * @param[in] ev The event context this async request will be driven by
47 * @retval A new async request
49 * The new async request will be initialized in state ASYNC_REQ_IN_PROGRESS
52 struct async_req *async_req_new(TALLOC_CTX *mem_ctx)
54 struct async_req *result;
56 result = TALLOC_ZERO_P(mem_ctx, struct async_req);
60 result->state = ASYNC_REQ_IN_PROGRESS;
61 result->print = async_req_print;
66 * @brief An async request has successfully finished
67 * @param[in] req The finished request
69 * async_req_done is to be used by implementors of async requests. When a
70 * request is successfully finished, this function calls the user's completion
74 void async_req_done(struct async_req *req)
76 req->status = NT_STATUS_OK;
77 req->state = ASYNC_REQ_DONE;
78 if (req->async.fn != NULL) {
84 * @brief An async request has seen an error
85 * @param[in] req The request with an error
86 * @param[in] status The error code
88 * async_req_done is to be used by implementors of async requests. When a
89 * request can not successfully completed, the implementation should call this
90 * function with the appropriate status code.
93 void async_req_error(struct async_req *req, NTSTATUS status)
96 req->state = ASYNC_REQ_ERROR;
97 if (req->async.fn != NULL) {
103 * @brief Timed event callback
104 * @param[in] ev Event context
105 * @param[in] te The timed event
106 * @param[in] now zero time
107 * @param[in] priv The async request to be finished
110 static void async_trigger(struct event_context *ev, struct timed_event *te,
111 struct timeval now, void *priv)
113 struct async_req *req = talloc_get_type_abort(priv, struct async_req);
116 if (NT_STATUS_IS_OK(req->status)) {
120 async_req_error(req, req->status);
125 * @brief Finish a request before it started processing
126 * @param[in] req The finished request
127 * @param[in] status The success code
129 * An implementation of an async request might find that it can either finish
130 * the request without waiting for an external event, or it can't even start
131 * the engine. To present the illusion of a callback to the user of the API,
132 * the implementation can call this helper function which triggers an
133 * immediate timed event. This way the caller can use the same calling
134 * conventions, independent of whether the request was actually deferred.
137 bool async_post_status(struct async_req *req, struct event_context *ev,
140 req->status = status;
142 if (event_add_timed(ev, req, timeval_zero(),
143 async_trigger, req) == NULL) {
150 * @brief Helper function for nomem check
151 * @param[in] p The pointer to be checked
152 * @param[in] req The request being processed
154 * Convenience helper to easily check alloc failure within a callback
155 * implementing the next step of an async request.
157 * Call pattern would be
159 * p = talloc(mem_ctx, bla);
160 * if (async_req_nomem(p, req)) {
166 bool async_req_nomem(const void *p, struct async_req *req)
171 async_req_error(req, NT_STATUS_NO_MEMORY);
175 bool async_req_is_error(struct async_req *req, NTSTATUS *status)
177 if (req->state < ASYNC_REQ_DONE) {
178 *status = NT_STATUS_INTERNAL_ERROR;
181 if (req->state == ASYNC_REQ_ERROR) {
182 *status = req->status;
188 NTSTATUS async_req_simple_recv(struct async_req *req)
192 if (async_req_is_error(req, &status)) {
198 static void async_req_timedout(struct event_context *ev,
199 struct timed_event *te,
203 struct async_req *req = talloc_get_type_abort(
204 priv, struct async_req);
206 async_req_error(req, NT_STATUS_IO_TIMEOUT);
209 bool async_req_set_timeout(struct async_req *req, struct event_context *ev,
212 return (event_add_timed(ev, req,
213 timeval_current_ofs(to.tv_sec, to.tv_usec),
214 async_req_timedout, req)
218 struct async_req *async_wait_send(TALLOC_CTX *mem_ctx,
219 struct event_context *ev,
222 struct async_req *result;
224 result = async_req_new(mem_ctx);
225 if (result == NULL) {
228 if (!async_req_set_timeout(result, ev, to)) {
235 NTSTATUS async_wait_recv(struct async_req *req)
240 struct async_queue_entry {
241 struct async_queue_entry *prev, *next;
242 struct async_req_queue *queue;
243 struct async_req *req;
244 void (*trigger)(struct async_req *req);
247 struct async_req_queue {
248 struct async_queue_entry *queue;
251 struct async_req_queue *async_req_queue_init(TALLOC_CTX *mem_ctx)
253 return TALLOC_ZERO_P(mem_ctx, struct async_req_queue);
256 static int async_queue_entry_destructor(struct async_queue_entry *e)
258 struct async_req_queue *queue = e->queue;
260 DLIST_REMOVE(queue->queue, e);
262 if (queue->queue != NULL) {
263 queue->queue->trigger(queue->queue->req);
269 static void async_req_immediate_trigger(struct event_context *ev,
270 struct timed_event *te,
274 struct async_queue_entry *e = talloc_get_type_abort(
275 priv, struct async_queue_entry);
281 bool async_req_enqueue(struct async_req_queue *queue, struct event_context *ev,
282 struct async_req *req,
283 void (*trigger)(struct async_req *req))
285 struct async_queue_entry *e;
288 busy = (queue->queue != NULL);
290 e = talloc(req, struct async_queue_entry);
296 e->trigger = trigger;
299 DLIST_ADD_END(queue->queue, e, struct async_queue_entry *);
300 talloc_set_destructor(e, async_queue_entry_destructor);
303 struct timed_event *te;
305 te = event_add_timed(ev, e, timeval_zero(),
306 async_req_immediate_trigger,
317 bool _async_req_setup(TALLOC_CTX *mem_ctx, struct async_req **preq,
318 void *pstate, size_t state_size, const char *typename)
320 struct async_req *req;
321 void **ppstate = (void **)pstate;
324 req = async_req_new(mem_ctx);
328 state = talloc_size(req, state_size);
333 talloc_set_name(state, typename);
334 req->private_data = state;