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/>.
20 #ifndef __ASYNC_REQ_H__
21 #define __ASYNC_REQ_H__
23 #include "lib/talloc/talloc.h"
26 * An async request moves between the following 4 states:
29 enum async_req_state
{
31 * we are creating the request
35 * we are waiting the request to complete
37 ASYNC_REQ_IN_PROGRESS
,
39 * the request is finished
43 * A user error has occured
51 * No memory in between
57 * @brief An async request
59 * This represents an async request being processed by callbacks via an event
60 * context. A user can issue for example a write request to a socket, giving
61 * an implementation function the fd, the buffer and the number of bytes to
62 * transfer. The function issuing the request will immediately return without
63 * blocking most likely without having sent anything. The API user then fills
64 * in req->async.fn and req->async.priv, functions that are called when the
65 * request is finished.
67 * It is up to the user of the async request to talloc_free it after it has
68 * finished. This can happen while the completion function is called.
73 * @brief The external state - will be queried by the caller
75 * While the async request is being processed, state will remain in
76 * ASYNC_REQ_IN_PROGRESS. A request is finished if
77 * req->state>=ASYNC_REQ_DONE.
79 enum async_req_state state
;
82 * @brief Private pointer for the actual implementation
84 * The implementation doing the work for the async request needs a
85 * current state like for example a fd event. The user of an async
86 * request should not touch this.
91 * @brief Print yourself, for debugging purposes
93 * Async requests are opaque data structures. The implementation of an
94 * async request can define a custom function to print more debug
97 char *(*print
)(TALLOC_CTX
*mem_ctx
, struct async_req
*);
100 * @brief status code when finished
102 * This status can be queried in the async completion function. It
103 * will be set to 0 when everything went fine.
108 * @brief What to do on completion
110 * This is used for the user of an async request, fn is called when
111 * the request completes, either successfully or with an error.
115 * @brief Completion function
116 * Completion function, to be filled by the API user
118 void (*fn
)(struct async_req
*);
120 * @brief Private data for the completion function
126 struct async_req
*async_req_new(TALLOC_CTX
*mem_ctx
);
128 char *async_req_print(TALLOC_CTX
*mem_ctx
, struct async_req
*req
);
130 void async_req_done(struct async_req
*req
);
132 void async_req_error(struct async_req
*req
, uint64_t error
);
134 bool async_req_nomem(const void *p
, struct async_req
*req
);
136 bool async_post_error(struct async_req
*req
, struct tevent_context
*ev
,
139 bool async_req_is_error(struct async_req
*req
, enum async_req_state
*state
,
142 struct async_req_queue
;
144 struct async_req_queue
*async_req_queue_init(TALLOC_CTX
*mem_ctx
);
146 bool async_req_enqueue(struct async_req_queue
*queue
,
147 struct tevent_context
*ev
,
148 struct async_req
*req
,
149 void (*trigger
)(struct async_req
*req
));
151 bool _async_req_setup(TALLOC_CTX
*mem_ctx
, struct async_req
**preq
,
152 void *pstate
, size_t state_size
, const char *typename
);
154 #define async_req_setup(_mem_ctx, _preq, _pstate, type) \
155 _async_req_setup((_mem_ctx), (_preq), (_pstate), sizeof(type), #type)