talloc: use the system pytalloc-util for python3 as well
[sfrench/samba-autobuild/.git] / lib / tevent / tevent_internal.h
1 /* 
2    Unix SMB/CIFS implementation.
3
4    generalised event loop handling
5
6    INTERNAL STRUCTS. THERE ARE NO API GUARANTEES.
7    External users should only ever have to include this header when 
8    implementing new tevent backends.
9
10    Copyright (C) Stefan Metzmacher 2005-2009
11
12      ** NOTE! The following LGPL license applies to the tevent
13      ** library. This does NOT imply that all of Samba is released
14      ** under the LGPL
15
16    This library is free software; you can redistribute it and/or
17    modify it under the terms of the GNU Lesser General Public
18    License as published by the Free Software Foundation; either
19    version 3 of the License, or (at your option) any later version.
20
21    This library is distributed in the hope that it will be useful,
22    but WITHOUT ANY WARRANTY; without even the implied warranty of
23    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
24    Lesser General Public License for more details.
25
26    You should have received a copy of the GNU Lesser General Public
27    License along with this library; if not, see <http://www.gnu.org/licenses/>.
28 */
29
30 struct tevent_req {
31         /**
32          * @brief What to do on completion
33          *
34          * This is used for the user of an async request, fn is called when
35          * the request completes, either successfully or with an error.
36          */
37         struct {
38                 /**
39                  * @brief Completion function
40                  * Completion function, to be filled by the API user
41                  */
42                 tevent_req_fn fn;
43                 /**
44                  * @brief Private data for the completion function
45                  */
46                 void *private_data;
47         } async;
48
49         /**
50          * @brief Private state pointer for the actual implementation
51          *
52          * The implementation doing the work for the async request needs to
53          * keep around current data like for example a fd event. The user of
54          * an async request should not touch this.
55          */
56         void *data;
57
58         /**
59          * @brief A function to overwrite the default print function
60          *
61          * The implementation doing the work may want to implement a
62          * custom function to print the text representation of the async
63          * request.
64          */
65         tevent_req_print_fn private_print;
66
67         /**
68          * @brief A function to cancel the request
69          *
70          * The implementation might want to set a function
71          * that is called when the tevent_req_cancel() function
72          * was called.
73          */
74         tevent_req_cancel_fn private_cancel;
75
76         /**
77          * @brief A function to cleanup the request
78          *
79          * The implementation might want to set a function
80          * that is called before the tevent_req_done() and tevent_req_error()
81          * trigger the callers callback function.
82          */
83         struct {
84                 tevent_req_cleanup_fn fn;
85                 enum tevent_req_state state;
86         } private_cleanup;
87
88         /**
89          * @brief Internal state of the request
90          *
91          * Callers should only access this via functions and never directly.
92          */
93         struct {
94                 /**
95                  * @brief The talloc type of the data pointer
96                  *
97                  * This is filled by the tevent_req_create() macro.
98                  *
99                  * This for debugging only.
100                  */
101                 const char *private_type;
102
103                 /**
104                  * @brief The location where the request was created
105                  *
106                  * This uses the __location__ macro via the tevent_req_create()
107                  * macro.
108                  *
109                  * This for debugging only.
110                  */
111                 const char *create_location;
112
113                 /**
114                  * @brief The location where the request was finished
115                  *
116                  * This uses the __location__ macro via the tevent_req_done(),
117                  * tevent_req_error() or tevent_req_nomem() macro.
118                  *
119                  * This for debugging only.
120                  */
121                 const char *finish_location;
122
123                 /**
124                  * @brief The location where the request was canceled
125                  *
126                  * This uses the __location__ macro via the
127                  * tevent_req_cancel() macro.
128                  *
129                  * This for debugging only.
130                  */
131                 const char *cancel_location;
132
133                 /**
134                  * @brief The external state - will be queried by the caller
135                  *
136                  * While the async request is being processed, state will remain in
137                  * TEVENT_REQ_IN_PROGRESS. A request is finished if
138                  * req->state>=TEVENT_REQ_DONE.
139                  */
140                 enum tevent_req_state state;
141
142                 /**
143                  * @brief status code when finished
144                  *
145                  * This status can be queried in the async completion function. It
146                  * will be set to 0 when everything went fine.
147                  */
148                 uint64_t error;
149
150                 /**
151                  * @brief the immediate event used by tevent_req_post
152                  *
153                  */
154                 struct tevent_immediate *trigger;
155
156                 /**
157                  * @brief An event context which will be used to
158                  *        defer the _tevent_req_notify_callback().
159                  */
160                 struct tevent_context *defer_callback_ev;
161
162                 /**
163                  * @brief the timer event if tevent_req_set_endtime was used
164                  *
165                  */
166                 struct tevent_timer *timer;
167         } internal;
168 };
169
170 struct tevent_fd {
171         struct tevent_fd *prev, *next;
172         struct tevent_context *event_ctx;
173         int fd;
174         uint16_t flags; /* see TEVENT_FD_* flags */
175         tevent_fd_handler_t handler;
176         tevent_fd_close_fn_t close_fn;
177         /* this is private for the specific handler */
178         void *private_data;
179         /* this is for debugging only! */
180         const char *handler_name;
181         const char *location;
182         /* this is private for the events_ops implementation */
183         uint64_t additional_flags;
184         void *additional_data;
185 };
186
187 struct tevent_timer {
188         struct tevent_timer *prev, *next;
189         struct tevent_context *event_ctx;
190         struct timeval next_event;
191         tevent_timer_handler_t handler;
192         /* this is private for the specific handler */
193         void *private_data;
194         /* this is for debugging only! */
195         const char *handler_name;
196         const char *location;
197         /* this is private for the events_ops implementation */
198         void *additional_data;
199 };
200
201 struct tevent_immediate {
202         struct tevent_immediate *prev, *next;
203         struct tevent_context *event_ctx;
204         tevent_immediate_handler_t handler;
205         /* this is private for the specific handler */
206         void *private_data;
207         /* this is for debugging only! */
208         const char *handler_name;
209         const char *create_location;
210         const char *schedule_location;
211         /* this is private for the events_ops implementation */
212         void (*cancel_fn)(struct tevent_immediate *im);
213         void *additional_data;
214 };
215
216 struct tevent_signal {
217         struct tevent_signal *prev, *next;
218         struct tevent_context *event_ctx;
219         int signum;
220         int sa_flags;
221         tevent_signal_handler_t handler;
222         /* this is private for the specific handler */
223         void *private_data;
224         /* this is for debugging only! */
225         const char *handler_name;
226         const char *location;
227         /* this is private for the events_ops implementation */
228         void *additional_data;
229 };
230
231 struct tevent_threaded_context {
232         struct tevent_threaded_context *next, *prev;
233
234 #ifdef HAVE_PTHREAD
235         pthread_mutex_t event_ctx_mutex;
236 #endif
237         struct tevent_context *event_ctx;
238         int wakeup_fd;
239 };
240
241 struct tevent_debug_ops {
242         void (*debug)(void *context, enum tevent_debug_level level,
243                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
244         void *context;
245 };
246
247 void tevent_debug(struct tevent_context *ev, enum tevent_debug_level level,
248                   const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
249
250 struct tevent_context {
251         /* the specific events implementation */
252         const struct tevent_ops *ops;
253
254         /*
255          * The following three pointers are queried on every loop_once
256          * in the order in which they appear here. Not measured, but
257          * hopefully putting them at the top together with "ops"
258          * should make tevent a *bit* more cache-friendly than before.
259          */
260
261         /* list of signal events - used by common code */
262         struct tevent_signal *signal_events;
263
264         /* List of threaded job indicators */
265         struct tevent_threaded_context *threaded_contexts;
266
267         /* list of immediate events - used by common code */
268         struct tevent_immediate *immediate_events;
269
270         /* list of fd events - used by common code */
271         struct tevent_fd *fd_events;
272
273         /* list of timed events - used by common code */
274         struct tevent_timer *timer_events;
275
276         /* List of scheduled immediates */
277         pthread_mutex_t scheduled_mutex;
278         struct tevent_immediate *scheduled_immediates;
279
280         /* this is private for the events_ops implementation */
281         void *additional_data;
282
283         /* pipe hack used with signal handlers */
284         struct tevent_fd *wakeup_fde;
285         int wakeup_fd;          /* fd to write into */
286 #ifndef HAVE_EVENT_FD
287         int wakeup_read_fd;
288 #endif
289
290         /* debugging operations */
291         struct tevent_debug_ops debug_ops;
292
293         /* info about the nesting status */
294         struct {
295                 bool allowed;
296                 uint32_t level;
297                 tevent_nesting_hook hook_fn;
298                 void *hook_private;
299         } nesting;
300
301         struct {
302                 tevent_trace_callback_t callback;
303                 void *private_data;
304         } tracing;
305
306         /*
307          * an optimization pointer into timer_events
308          * used by used by common code via
309          * tevent_common_add_timer_v2()
310          */
311         struct tevent_timer *last_zero_timer;
312
313 #ifdef HAVE_PTHREAD
314         struct tevent_context *prev, *next;
315 #endif
316 };
317
318 const struct tevent_ops *tevent_find_ops_byname(const char *name);
319
320 int tevent_common_context_destructor(struct tevent_context *ev);
321 int tevent_common_loop_wait(struct tevent_context *ev,
322                             const char *location);
323
324 int tevent_common_fd_destructor(struct tevent_fd *fde);
325 struct tevent_fd *tevent_common_add_fd(struct tevent_context *ev,
326                                        TALLOC_CTX *mem_ctx,
327                                        int fd,
328                                        uint16_t flags,
329                                        tevent_fd_handler_t handler,
330                                        void *private_data,
331                                        const char *handler_name,
332                                        const char *location);
333 void tevent_common_fd_set_close_fn(struct tevent_fd *fde,
334                                    tevent_fd_close_fn_t close_fn);
335 uint16_t tevent_common_fd_get_flags(struct tevent_fd *fde);
336 void tevent_common_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
337
338 struct tevent_timer *tevent_common_add_timer(struct tevent_context *ev,
339                                              TALLOC_CTX *mem_ctx,
340                                              struct timeval next_event,
341                                              tevent_timer_handler_t handler,
342                                              void *private_data,
343                                              const char *handler_name,
344                                              const char *location);
345 struct tevent_timer *tevent_common_add_timer_v2(struct tevent_context *ev,
346                                                 TALLOC_CTX *mem_ctx,
347                                                 struct timeval next_event,
348                                                 tevent_timer_handler_t handler,
349                                                 void *private_data,
350                                                 const char *handler_name,
351                                                 const char *location);
352 struct timeval tevent_common_loop_timer_delay(struct tevent_context *);
353
354 void tevent_common_schedule_immediate(struct tevent_immediate *im,
355                                       struct tevent_context *ev,
356                                       tevent_immediate_handler_t handler,
357                                       void *private_data,
358                                       const char *handler_name,
359                                       const char *location);
360 bool tevent_common_loop_immediate(struct tevent_context *ev);
361 void tevent_common_threaded_activate_immediate(struct tevent_context *ev);
362
363 bool tevent_common_have_events(struct tevent_context *ev);
364 int tevent_common_wakeup_init(struct tevent_context *ev);
365 int tevent_common_wakeup_fd(int fd);
366 int tevent_common_wakeup(struct tevent_context *ev);
367
368 struct tevent_signal *tevent_common_add_signal(struct tevent_context *ev,
369                                                TALLOC_CTX *mem_ctx,
370                                                int signum,
371                                                int sa_flags,
372                                                tevent_signal_handler_t handler,
373                                                void *private_data,
374                                                const char *handler_name,
375                                                const char *location);
376 int tevent_common_check_signal(struct tevent_context *ev);
377 void tevent_cleanup_pending_signal_handlers(struct tevent_signal *se);
378
379 bool tevent_standard_init(void);
380 bool tevent_select_init(void);
381 bool tevent_poll_init(void);
382 void tevent_poll_event_add_fd_internal(struct tevent_context *ev,
383                                        struct tevent_fd *fde);
384 bool tevent_poll_mt_init(void);
385 #ifdef HAVE_EPOLL
386 bool tevent_epoll_init(void);
387 void tevent_epoll_set_panic_fallback(struct tevent_context *ev,
388                         bool (*panic_fallback)(struct tevent_context *ev,
389                                                bool replay));
390 #endif
391 #ifdef HAVE_SOLARIS_PORTS
392 bool tevent_port_init(void);
393 #endif
394
395
396 void tevent_trace_point_callback(struct tevent_context *ev,
397                                  enum tevent_trace_point);