tsocket: remove DGRAM support from tsocket_context
[ira/wip.git] / lib / async_req / async_req.h
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