/* [<][>][^][v][top][bottom][index][help] */
1 /*
2 Unix SMB/CIFS implementation.
3 Infrastructure for async requests
4 Copyright (C) Volker Lendecke 2008
5
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.
10
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.
15
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/>.
18 */
19
20 #ifndef __ASYNC_REQ_H__
21 #define __ASYNC_REQ_H__
22
23 #include "lib/talloc/talloc.h"
24
25 /**
26 * An async request moves between the following 4 states:
27 */
28
29 enum async_req_state {
30 /**
31 * we are creating the request
32 */
33 ASYNC_REQ_INIT,
34 /**
35 * we are waiting the request to complete
36 */
37 ASYNC_REQ_IN_PROGRESS,
38 /**
39 * the request is finished
40 */
41 ASYNC_REQ_DONE,
42 /**
43 * A user error has occured
44 */
45 ASYNC_REQ_USER_ERROR,
46 /**
47 * Request timed out
48 */
49 ASYNC_REQ_TIMED_OUT,
50 /**
51 * No memory in between
52 */
53 ASYNC_REQ_NO_MEMORY
54 };
55
56 /**
57 * @brief An async request
58 *
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.
66 *
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.
69 */
70
71 struct async_req {
72 /**
73 * @brief The external state - will be queried by the caller
74 *
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.
78 */
79 enum async_req_state state;
80
81 /**
82 * @brief Private pointer for the actual implementation
83 *
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.
87 */
88 void *private_data;
89
90 /**
91 * @brief Print yourself, for debugging purposes
92 *
93 * Async requests are opaque data structures. The implementation of an
94 * async request can define a custom function to print more debug
95 * info.
96 */
97 char *(*print)(TALLOC_CTX *mem_ctx, struct async_req *);
98
99 /**
100 * @brief status code when finished
101 *
102 * This status can be queried in the async completion function. It
103 * will be set to 0 when everything went fine.
104 **/
105 uint64_t error;
106
107 /**
108 * @brief What to do on completion
109 *
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.
112 */
113 struct {
114 /**
115 * @brief Completion function
116 * Completion function, to be filled by the API user
117 */
118 void (*fn)(struct async_req *);
119 /**
120 * @brief Private data for the completion function
121 */
122 void *priv;
123 } async;
124 };
125
126 struct async_req *async_req_new(TALLOC_CTX *mem_ctx);
127
128 char *async_req_print(TALLOC_CTX *mem_ctx, struct async_req *req);
129
130 void async_req_done(struct async_req *req);
131
132 void async_req_error(struct async_req *req, uint64_t error);
133
134 bool async_req_nomem(const void *p, struct async_req *req);
135
136 bool async_post_error(struct async_req *req, struct tevent_context *ev,
137 uint64_t error);
138
139 bool async_req_is_error(struct async_req *req, enum async_req_state *state,
140 uint64_t *error);
141
142 struct async_req_queue;
143
144 struct async_req_queue *async_req_queue_init(TALLOC_CTX *mem_ctx);
145
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));
150
151 bool _async_req_setup(TALLOC_CTX *mem_ctx, struct async_req **preq,
152 void *pstate, size_t state_size, const char *typename);
153
154 #define async_req_setup(_mem_ctx, _preq, _pstate, type) \
155 _async_req_setup((_mem_ctx), (_preq), (_pstate), sizeof(type), #type)
156
157
158 #endif