117
324
#define tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
118
325
_tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data, \
119
326
#handler, __location__)
331
* @brief Pass a single time through the mainloop
333
* This will process any appropriate signal, immediate, fd and timer events
335
* @param[in] ev The event context to process
337
* @return Zero on success, nonzero if an internal error occurred
339
int tevent_loop_once(struct tevent_context *ev);
121
341
int _tevent_loop_once(struct tevent_context *ev, const char *location);
122
342
#define tevent_loop_once(ev) \
123
_tevent_loop_once(ev, __location__) \
343
_tevent_loop_once(ev, __location__)
348
* @brief Run the mainloop
350
* The mainloop will run until there are no events remaining to be processed
352
* @param[in] ev The event context to process
354
* @return Zero if all events have been processed. Nonzero if an internal
357
int tevent_loop_wait(struct tevent_context *ev);
125
359
int _tevent_loop_wait(struct tevent_context *ev, const char *location);
126
360
#define tevent_loop_wait(ev) \
127
_tevent_loop_wait(ev, __location__) \
361
_tevent_loop_wait(ev, __location__)
366
* Assign a function to run when a tevent_fd is freed
368
* This function is a destructor for the tevent_fd. It does not automatically
369
* close the file descriptor. If this is the desired behavior, then it must be
370
* performed by the close_fn.
372
* @param[in] fde File descriptor event on which to set the destructor
373
* @param[in] close_fn Destructor to execute when fde is freed
129
375
void tevent_fd_set_close_fn(struct tevent_fd *fde,
130
376
tevent_fd_close_fn_t close_fn);
379
* Automatically close the file descriptor when the tevent_fd is freed
381
* This function calls close(fd) internally.
383
* @param[in] fde File descriptor event to auto-close
131
385
void tevent_fd_set_auto_close(struct tevent_fd *fde);
388
* Return the flags set on this file descriptor event
390
* @param[in] fde File descriptor event to query
392
* @return The flags set on the event. See #TEVENT_FD_READ and
132
395
uint16_t tevent_fd_get_flags(struct tevent_fd *fde);
398
* Set flags on a file descriptor event
400
* @param[in] fde File descriptor event to set
401
* @param[in] flags Flags to set on the event. See #TEVENT_FD_READ and
133
404
void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
407
* Query whether tevent supports signal handling
409
* @param[in] ev An initialized tevent context
411
* @return True if this platform and tevent context support signal handling
135
413
bool tevent_signal_support(struct tevent_context *ev);
137
415
void tevent_set_abort_fn(void (*abort_fn)(const char *reason));
139
417
/* bits for file descriptor event flags */
420
* Monitor a file descriptor for write availability
140
422
#define TEVENT_FD_READ 1
424
* Monitor a file descriptor for data to be read
141
426
#define TEVENT_FD_WRITE 2
429
* Convenience function for declaring a tevent_fd writable
143
431
#define TEVENT_FD_WRITEABLE(fde) \
144
432
tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
435
* Convenience function for declaring a tevent_fd readable
145
437
#define TEVENT_FD_READABLE(fde) \
146
438
tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
441
* Convenience function for declaring a tevent_fd non-writable
148
443
#define TEVENT_FD_NOT_WRITEABLE(fde) \
149
444
tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
447
* Convenience function for declaring a tevent_fd non-readable
150
449
#define TEVENT_FD_NOT_READABLE(fde) \
151
450
tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
453
* Debug level of tevent
154
455
enum tevent_debug_level {
155
456
TEVENT_DEBUG_FATAL,
156
457
TEVENT_DEBUG_ERROR,
158
459
TEVENT_DEBUG_TRACE
463
* @brief The tevent debug callbac.
465
* @param[in] context The memory context to use.
467
* @param[in] level The debug level.
469
* @param[in] fmt The format string.
471
* @param[in] ap The arguments for the format string.
473
typedef void (*tevent_debug_fn)(void *context,
474
enum tevent_debug_level level,
476
va_list ap) PRINTF_ATTRIBUTE(3,0);
479
* Set destination for tevent debug messages
481
* @param[in] ev Event context to debug
482
* @param[in] debug Function to handle output printing
483
* @param[in] context The context to pass to the debug function.
485
* @return Always returns 0 as of version 0.9.8
487
* @note Default is to emit no debug messages
161
489
int tevent_set_debug(struct tevent_context *ev,
162
void (*debug)(void *context,
163
enum tevent_debug_level level,
165
va_list ap) PRINTF_ATTRIBUTE(3,0),
490
tevent_debug_fn debug,
494
* Designate stderr for debug message output
496
* @param[in] ev Event context to debug
498
* @note This function will only output TEVENT_DEBUG_FATAL, TEVENT_DEBUG_ERROR
499
* and TEVENT_DEBUG_WARNING messages. For TEVENT_DEBUG_TRACE, please define a
500
* function for tevent_set_debug()
167
502
int tevent_set_debug_stderr(struct tevent_context *ev);
170
* An async request moves between the following 4 states:
509
* @defgroup tevent_request The tevent request functions.
512
* A tevent_req represents an asynchronous computation.
514
* The tevent_req group of API calls is the recommended way of
515
* programming async computations within tevent. In particular the
516
* file descriptor (tevent_add_fd) and timer (tevent_add_timed) events
517
* are considered too low-level to be used in larger computations. To
518
* read and write from and to sockets, Samba provides two calls on top
519
* of tevent_add_fd: read_packet_send/recv and writev_send/recv. These
520
* requests are much easier to compose than the low-level event
521
* handlers called from tevent_add_fd.
523
* A lot of the simplicity tevent_req has brought to the notoriously
524
* hairy async programming came via a set of conventions that every
525
* async computation programmed should follow. One central piece of
526
* these conventions is the naming of routines and variables.
528
* Every async computation needs a name (sensibly called "computation"
529
* down from here). From this name quite a few naming conventions are
532
* Every computation that requires local state needs a
534
* struct computation_state {
538
* Even if no local variables are required, such a state struct should
539
* be created containing a dummy variable. Quite a few helper
540
* functions and macros (for example tevent_req_create()) assume such
543
* An async computation is started by a computation_send
544
* function. When it is finished, its result can be received by a
545
* computation_recv function. For an example how to set up an async
546
* computation, see the code example in the documentation for
547
* tevent_req_create() and tevent_req_post(). The prototypes for _send
548
* and _recv functions should follow some conventions:
551
* struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
552
* struct tevent_req *ev,
554
* int computation_recv(struct tevent_req *req, ... further output args);
557
* The "int" result of computation_recv() depends on the result the
558
* sync version of the function would have, "int" is just an example
561
* Another important piece of the conventions is that the program flow
562
* is interrupted as little as possible. Because a blocking
563
* sub-computation requires that the flow needs to continue in a
564
* separate function that is the logical sequel of some computation,
565
* it should lexically follow sending off the blocking
566
* sub-computation. Setting the callback function via
567
* tevent_req_set_callback() requires referencing a function lexically
568
* below the call to tevent_req_set_callback(), forward declarations
569
* are required. A lot of the async computations thus begin with a
570
* sequence of declarations such as
573
* static void computation_step1_done(struct tevent_req *subreq);
574
* static void computation_step2_done(struct tevent_req *subreq);
575
* static void computation_step3_done(struct tevent_req *subreq);
578
* It really helps readability a lot to do these forward declarations,
579
* because the lexically sequential program flow makes the async
580
* computations almost as clear to read as a normal, sync program
583
* It is up to the user of the async computation to talloc_free it
584
* after it has finished. If an async computation should be aborted,
585
* the tevent_req structure can be talloc_free'ed. After it has
586
* finished, it should talloc_free'ed by the API user.
592
* An async request moves from TEVENT_REQ_INIT to
593
* TEVENT_REQ_IN_PROGRESS. All other states are valid after a request
172
596
enum tevent_req_state {
174
* we are creating the request
598
* We are creating the request
178
* we are waiting the request to complete
602
* We are waiting the request to complete
180
604
TEVENT_REQ_IN_PROGRESS,
182
* the request is finished
606
* The request is finished successfully
186
* A user error has occured
610
* A user error has occurred. The user error has been
611
* indicated by tevent_req_error(), it can be retrieved via
612
* tevent_req_is_error().
188
614
TEVENT_REQ_USER_ERROR,
616
* Request timed out after the timeout set by tevent_req_set_endtime.
192
618
TEVENT_REQ_TIMED_OUT,
194
* No memory in between
620
* An internal allocation has failed, or tevent_req_nomem has
621
* been given a NULL pointer as the first argument.
196
623
TEVENT_REQ_NO_MEMORY,
198
* the request is already received by the caller
625
* The request has been received by the caller. No further
200
628
TEVENT_REQ_RECEIVED
204
632
* @brief An async request
206
* This represents an async request being processed by callbacks via an event
207
* context. A user can issue for example a write request to a socket, giving
208
* an implementation function the fd, the buffer and the number of bytes to
209
* transfer. The function issuing the request will immediately return without
210
* blocking most likely without having sent anything. The API user then fills
211
* in req->async.fn and req->async.private_data, functions that are called
212
* when the request is finished.
214
* It is up to the user of the async request to talloc_free it after it has
215
* finished. This can happen while the completion function is called.
218
634
struct tevent_req;
220
typedef void (*tevent_req_fn)(struct tevent_req *);
637
* @brief A tevent request callback function.
639
* @param[in] req The tevent async request which executed this callback.
641
typedef void (*tevent_req_fn)(struct tevent_req *req);
644
* @brief Set an async request callback.
646
* See the documentation of tevent_req_post() for an example how this
647
* is supposed to be used.
649
* @param[in] req The async request to set the callback.
651
* @param[in] fn The callback function to set.
653
* @param[in] pvt A pointer to private data to pass to the async request
222
656
void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt);
660
* @brief Get the private data cast to the given type for a callback from
661
* a tevent request structure.
664
* static void computation_done(struct tevent_req *subreq) {
665
* struct tevent_req *req = tevent_req_callback_data(subreq, struct tevent_req);
666
* struct computation_state *state = tevent_req_data(req, struct computation_state);
667
* .... more things, eventually maybe call tevent_req_done(req);
671
* @param[in] req The structure to get the callback data from.
673
* @param[in] type The type of the private callback data to get.
675
* @return The type casted private data set NULL if not set.
677
void *tevent_req_callback_data(struct tevent_req *req, #type);
223
679
void *_tevent_req_callback_data(struct tevent_req *req);
224
void *_tevent_req_data(struct tevent_req *req);
226
680
#define tevent_req_callback_data(_req, _type) \
227
681
talloc_get_type_abort(_tevent_req_callback_data(_req), _type)
686
* @brief Get the private data for a callback from a tevent request structure.
688
* @param[in] req The structure to get the callback data from.
690
* @param[in] req The structure to get the data from.
692
* @return The private data or NULL if not set.
694
void *tevent_req_callback_data_void(struct tevent_req *req);
228
696
#define tevent_req_callback_data_void(_req) \
229
697
_tevent_req_callback_data(_req)
702
* @brief Get the private data from a tevent request structure.
704
* When the tevent_req has been created by tevent_req_create, the
705
* result of tevent_req_data() is the state variable created by
706
* tevent_req_create() as a child of the req.
708
* @param[in] req The structure to get the private data from.
710
* @param[in] type The type of the private data
712
* @return The private data or NULL if not set.
714
void *tevent_req_data(struct tevent_req *req, #type);
716
void *_tevent_req_data(struct tevent_req *req);
230
717
#define tevent_req_data(_req, _type) \
231
718
talloc_get_type_abort(_tevent_req_data(_req), _type)
233
typedef char *(*tevent_req_print_fn)(struct tevent_req *, TALLOC_CTX *);
722
* @brief The print function which can be set for a tevent async request.
724
* @param[in] req The tevent async request.
726
* @param[in] ctx A talloc memory context which can be uses to allocate
729
* @return An allocated string buffer to print.
733
* static char *my_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
735
* struct my_data *data = tevent_req_data(req, struct my_data);
738
* result = tevent_req_default_print(mem_ctx, req);
739
* if (result == NULL) {
743
* return talloc_asprintf_append_buffer(result, "foo=%d, bar=%d",
744
* data->foo, data->bar);
748
typedef char *(*tevent_req_print_fn)(struct tevent_req *req, TALLOC_CTX *ctx);
751
* @brief This function sets a print function for the given request.
753
* This function can be used to setup a print function for the given request.
754
* This will be triggered if the tevent_req_print() function was
755
* called on the given request.
757
* @param[in] req The request to use.
759
* @param[in] fn A pointer to the print function
761
* @note This function should only be used for debugging.
235
763
void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn);
766
* @brief The default print function for creating debug messages.
768
* The function should not be used by users of the async API,
769
* but custom print function can use it and append custom text
772
* @param[in] req The request to be printed.
774
* @param[in] mem_ctx The memory context for the result.
776
* @return Text representation of request.
237
779
char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
782
* @brief Print an tevent_req structure in debug messages.
784
* This function should be used by callers of the async API.
786
* @param[in] mem_ctx The memory context for the result.
788
* @param[in] req The request to be printed.
790
* @return Text representation of request.
239
792
char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
241
typedef bool (*tevent_req_cancel_fn)(struct tevent_req *);
795
* @brief A typedef for a cancel function for a tevent request.
797
* @param[in] req The tevent request calling this function.
799
* @return True if the request could be canceled, false if not.
801
typedef bool (*tevent_req_cancel_fn)(struct tevent_req *req);
804
* @brief This function sets a cancel function for the given tevent request.
806
* This function can be used to setup a cancel function for the given request.
807
* This will be triggered if the tevent_req_cancel() function was
808
* called on the given request.
810
* @param[in] req The request to use.
812
* @param[in] fn A pointer to the cancel function.
243
814
void tevent_req_set_cancel_fn(struct tevent_req *req, tevent_req_cancel_fn fn);
818
* @brief Try to cancel the given tevent request.
820
* This function can be used to cancel the given request.
822
* It is only possible to cancel a request when the implementation
823
* has registered a cancel function via the tevent_req_set_cancel_fn().
825
* @param[in] req The request to use.
827
* @return This function returns true is the request is cancelable,
828
* othererwise false is returned.
830
* @note Even if the function returns true, the caller need to wait
831
* for the function to complete normally.
832
* Only the _recv() function of the given request indicates
833
* if the request was really canceled.
835
bool tevent_req_cancel(struct tevent_req *req);
245
837
bool _tevent_req_cancel(struct tevent_req *req, const char *location);
246
838
#define tevent_req_cancel(req) \
247
839
_tevent_req_cancel(req, __location__)
844
* @brief Create an async tevent request.
846
* The new async request will be initialized in state TEVENT_REQ_IN_PROGRESS.
849
* struct tevent_req *req;
850
* struct computation_state *state;
851
* req = tevent_req_create(mem_ctx, &state, struct computation_state);
854
* Tevent_req_create() creates the state variable as a talloc child of
855
* its result. The state variable should be used as the talloc parent
856
* for all temporary variables that are allocated during the async
857
* computation. This way, when the user of the async computation frees
858
* the request, the state as a talloc child will be free'd along with
859
* all the temporary variables hanging off the state.
861
* @param[in] mem_ctx The memory context for the result.
862
* @param[in] pstate Pointer to the private request state.
863
* @param[in] type The name of the request.
865
* @return A new async request. NULL on error.
867
struct tevent_req *tevent_req_create(TALLOC_CTX *mem_ctx,
868
void **pstate, #type);
249
870
struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
251
872
size_t state_size,
255
876
#define tevent_req_create(_mem_ctx, _pstate, _type) \
256
877
_tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
257
878
#_type, __location__)
882
* @brief Set a timeout for an async request.
884
* @param[in] req The request to set the timeout for.
886
* @param[in] ev The event context to use for the timer.
888
* @param[in] endtime The endtime of the request.
890
* @return True if succeeded, false if not.
259
892
bool tevent_req_set_endtime(struct tevent_req *req,
260
893
struct tevent_context *ev,
261
894
struct timeval endtime);
898
* @brief Call the notify callback of the given tevent request manually.
900
* @param[in] req The tevent request to call the notify function from.
902
* @see tevent_req_set_callback()
904
void tevent_req_notify_callback(struct tevent_req *req);
263
906
void _tevent_req_notify_callback(struct tevent_req *req, const char *location);
264
907
#define tevent_req_notify_callback(req) \
265
908
_tevent_req_notify_callback(req, __location__)
913
* @brief An async request has successfully finished.
915
* This function is to be used by implementors of async requests. When a
916
* request is successfully finished, this function calls the user's completion
919
* @param[in] req The finished request.
921
void tevent_req_done(struct tevent_req *req);
267
923
void _tevent_req_done(struct tevent_req *req,
268
924
const char *location);
269
925
#define tevent_req_done(req) \
270
926
_tevent_req_done(req, __location__)
931
* @brief An async request has seen an error.
933
* This function is to be used by implementors of async requests. When a
934
* request can not successfully completed, the implementation should call this
935
* function with the appropriate status code.
937
* If error is 0 the function returns false and does nothing more.
939
* @param[in] req The request with an error.
941
* @param[in] error The error code.
943
* @return On success true is returned, false if error is 0.
946
* int error = first_function();
947
* if (tevent_req_error(req, error)) {
951
* error = second_function();
952
* if (tevent_req_error(req, error)) {
956
* tevent_req_done(req);
960
bool tevent_req_error(struct tevent_req *req,
272
963
bool _tevent_req_error(struct tevent_req *req,
274
965
const char *location);
275
966
#define tevent_req_error(req, error) \
276
967
_tevent_req_error(req, error, __location__)
972
* @brief Helper function for nomem check.
974
* Convenience helper to easily check alloc failure within a callback
975
* implementing the next step of an async request.
977
* @param[in] p The pointer to be checked.
979
* @param[in] req The request being processed.
982
* p = talloc(mem_ctx, bla);
983
* if (tevent_req_nomem(p, req)) {
988
bool tevent_req_nomem(const void *p,
989
struct tevent_req *req);
278
991
bool _tevent_req_nomem(const void *p,
279
992
struct tevent_req *req,
280
993
const char *location);
281
994
#define tevent_req_nomem(p, req) \
282
995
_tevent_req_nomem(p, req, __location__)
999
* @brief Finish a request before the caller had the change to set the callback.
1001
* An implementation of an async request might find that it can either finish
1002
* the request without waiting for an external event, or it can not even start
1003
* the engine. To present the illusion of a callback to the user of the API,
1004
* the implementation can call this helper function which triggers an
1005
* immediate timed event. This way the caller can use the same calling
1006
* conventions, independent of whether the request was actually deferred.
1009
* struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
1010
* struct tevent_context *ev)
1012
* struct tevent_req *req, *subreq;
1013
* struct computation_state *state;
1014
* req = tevent_req_create(mem_ctx, &state, struct computation_state);
1015
* if (req == NULL) {
1018
* subreq = subcomputation_send(state, ev);
1019
* if (tevent_req_nomem(subreq, req)) {
1020
* return tevent_req_post(req, ev);
1022
* tevent_req_set_callback(subreq, computation_done, req);
1027
* @param[in] req The finished request.
1029
* @param[in] ev The tevent_context for the timed event.
1031
* @return The given request will be returned.
284
1033
struct tevent_req *tevent_req_post(struct tevent_req *req,
285
1034
struct tevent_context *ev);
1037
* @brief Check if the given request is still in progress.
1039
* It is typically used by sync wrapper functions.
1041
* @param[in] req The request to poll.
1043
* @return The boolean form of "is in progress".
287
1045
bool tevent_req_is_in_progress(struct tevent_req *req);
1048
* @brief Actively poll for the given request to finish.
1050
* This function is typically used by sync wrapper functions.
1052
* @param[in] req The request to poll.
1054
* @param[in] ev The tevent_context to be used.
1056
* @return On success true is returned. If a critical error has
1057
* happened in the tevent loop layer false is returned.
1058
* This is not the return value of the given request!
1060
* @note This should only be used if the given tevent context was created by the
1061
* caller, to avoid event loop nesting.
1064
* req = tstream_writev_queue_send(mem_ctx,
1069
* ok = tevent_req_poll(req, tctx->ev);
1070
* rc = tstream_writev_queue_recv(req, &sys_errno);
289
1074
bool tevent_req_poll(struct tevent_req *req,
290
1075
struct tevent_context *ev);
1078
* @brief Get the tevent request state and the actual error set by
1082
* int computation_recv(struct tevent_req *req, uint64_t *perr)
1084
* enum tevent_req_state state;
1086
* if (tevent_req_is_error(req, &state, &err)) {
1094
* @param[in] req The tevent request to get the error from.
1096
* @param[out] state A pointer to store the tevent request error state.
1098
* @param[out] error A pointer to store the error set by tevent_req_error().
1100
* @return True if the function could set error and state, false
1103
* @see tevent_req_error()
292
1105
bool tevent_req_is_error(struct tevent_req *req,
293
1106
enum tevent_req_state *state,
294
1107
uint64_t *error);
1110
* @brief Use as the last action of a _recv() function.
1112
* This function destroys the attached private data.
1114
* @param[in] req The finished request.
296
1116
void tevent_req_received(struct tevent_req *req);
1119
* @brief Create a tevent subrequest at a given time.
1121
* The idea is that always the same syntax for tevent requests.
1123
* @param[in] mem_ctx The talloc memory context to use.
1125
* @param[in] ev The event handle to setup the request.
1127
* @param[in] wakeup_time The time to wakeup and execute the request.
1129
* @return The new subrequest, NULL on error.
1133
* static void my_callback_wakeup_done(tevent_req *subreq)
1135
* struct tevent_req *req = tevent_req_callback_data(subreq,
1136
* struct tevent_req);
1139
* ok = tevent_wakeup_recv(subreq);
1140
* TALLOC_FREE(subreq);
1142
* tevent_req_error(req, -1);
1150
* subreq = tevent_wakeup_send(mem_ctx, ev, wakeup_time);
1151
* if (tevent_req_nomem(subreq, req)) {
1154
* tevent_set_callback(subreq, my_callback_wakeup_done, req);
1157
* @see tevent_wakeup_recv()
298
1159
struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx,
299
1160
struct tevent_context *ev,
300
1161
struct timeval wakeup_time);
1164
* @brief Check if the wakeup has been correctly executed.
1166
* This function needs to be called in the callback function set after calling
1167
* tevent_wakeup_send().
1169
* @param[in] req The tevent request to check.
1171
* @return True on success, false otherwise.
1173
* @see tevent_wakeup_recv()
301
1175
bool tevent_wakeup_recv(struct tevent_req *req);
1180
* @defgroup tevent_helpers The tevent helper functiions
1189
* @brief Compare two timeval values.
1191
* @param[in] tv1 The first timeval value to compare.
1193
* @param[in] tv2 The second timeval value to compare.
1195
* @return 0 if they are equal.
1196
* 1 if the first time is greater than the second.
1197
* -1 if the first time is smaller than the second.
303
1199
int tevent_timeval_compare(const struct timeval *tv1,
304
1200
const struct timeval *tv2);
1203
* @brief Get a zero timval value.
1205
* @return A zero timval value.
306
1207
struct timeval tevent_timeval_zero(void);
1210
* @brief Get a timeval value for the current time.
1212
* @return A timval value with the current time.
308
1214
struct timeval tevent_timeval_current(void);
1217
* @brief Get a timeval structure with the given values.
1219
* @param[in] secs The seconds to set.
1221
* @param[in] usecs The milliseconds to set.
1223
* @return A timeval structure with the given values.
310
1225
struct timeval tevent_timeval_set(uint32_t secs, uint32_t usecs);
1228
* @brief Get the difference between two timeval values.
1230
* @param[in] tv1 The first timeval.
1232
* @param[in] tv2 The second timeval.
1234
* @return A timeval structure with the difference between the
1235
* first and the second value.
312
1237
struct timeval tevent_timeval_until(const struct timeval *tv1,
313
1238
const struct timeval *tv2);
1241
* @brief Check if a given timeval structure is zero.
1243
* @param[in] tv The timeval to check if it is zero.
1245
* @return True if it is zero, false otherwise.
315
1247
bool tevent_timeval_is_zero(const struct timeval *tv);
1250
* @brief Add the given amount of time to a timeval structure.
1252
* @param[in] tv The timeval structure to add the time.
1254
* @param[in] secs The seconds to add to the timeval.
1256
* @param[in] usecs The milliseconds to add to the timeval.
1258
* @return The timeval structure with the new time.
317
1260
struct timeval tevent_timeval_add(const struct timeval *tv, uint32_t secs,
318
1261
uint32_t usecs);
1264
* @brief Get a timeval in the future with a specified offset from now.
1266
* @param[in] secs The seconds of the offset from now.
1268
* @param[in] usecs The milliseconds of the offset from now.
1270
* @return A timval with the given offset in the future.
320
1272
struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
1278
* @defgroup tevent_queue The tevent queue functions
1281
* A tevent_queue is used to queue up async requests that must be
1282
* serialized. For example writing buffers into a socket must be
1283
* serialized. Writing a large lump of data into a socket can require
1284
* multiple write(2) or send(2) system calls. If more than one async
1285
* request is outstanding to write large buffers into a socket, every
1286
* request must individually be completed before the next one begins,
1287
* even if multiple syscalls are required.
1289
* Take a look at @ref tevent_queue_tutorial for more details.
322
1293
struct tevent_queue;
1297
* @brief Create and start a tevent queue.
1299
* @param[in] mem_ctx The talloc memory context to allocate the queue.
1301
* @param[in] name The name to use to identify the queue.
1303
* @return An allocated tevent queue on success, NULL on error.
1305
* @see tevent_start()
1306
* @see tevent_stop()
1308
struct tevent_queue *tevent_queue_create(TALLOC_CTX *mem_ctx,
324
1311
struct tevent_queue *_tevent_queue_create(TALLOC_CTX *mem_ctx,
325
1312
const char *name,
326
1313
const char *location);
328
1315
#define tevent_queue_create(_mem_ctx, _name) \
329
1316
_tevent_queue_create((_mem_ctx), (_name), __location__)
1320
* @brief A callback trigger function run by the queue.
1322
* @param[in] req The tevent request the trigger function is executed on.
1324
* @param[in] private_data The private data pointer specified by
1325
* tevent_queue_add().
1327
* @see tevent_queue_add()
331
1329
typedef void (*tevent_queue_trigger_fn_t)(struct tevent_req *req,
332
1330
void *private_data);
1333
* @brief Add a tevent request to the queue.
1335
* @param[in] queue The queue to add the request.
1337
* @param[in] ev The event handle to use for the request.
1339
* @param[in] req The tevent request to add to the queue.
1341
* @param[in] trigger The function triggered by the queue when the request
1344
* @param[in] private_data The private data passed to the trigger function.
1346
* @return True if the request has been successfully added, false
333
1349
bool tevent_queue_add(struct tevent_queue *queue,
334
1350
struct tevent_context *ev,
335
1351
struct tevent_req *req,
336
1352
tevent_queue_trigger_fn_t trigger,
337
1353
void *private_data);
1356
* @brief Start a tevent queue.
1358
* The queue is started by default.
1360
* @param[in] queue The queue to start.
338
1362
void tevent_queue_start(struct tevent_queue *queue);
1365
* @brief Stop a tevent queue.
1367
* The queue is started by default.
1369
* @param[in] queue The queue to stop.
339
1371
void tevent_queue_stop(struct tevent_queue *queue);
1374
* @brief Get the length of the queue.
1376
* @param[in] queue The queue to get the length from.
1378
* @return The number of elements.
341
1380
size_t tevent_queue_length(struct tevent_queue *queue);
343
1382
typedef int (*tevent_nesting_hook)(struct tevent_context *ev,
added
removed
lib/tevent/tevent.h
