|
tevent 0.9.8
|
The tevent low-level API. More...
Topics | |
| The tevent request functions. | |
| A tevent_req represents an asynchronous computation. | |
Macros | |
| #define | TEVENT_FD_READ 1 |
| Monitor a file descriptor for data to be read and errors. | |
| #define | TEVENT_FD_WRITE 2 |
| Monitor a file descriptor for writeability. | |
| #define | TEVENT_FD_ERROR 4 |
| Monitor a file descriptor for errors. | |
| #define | TEVENT_FD_WRITEABLE(fde) |
| Convenience function for declaring a tevent_fd writable. | |
| #define | TEVENT_FD_READABLE(fde) |
| Convenience function for declaring a tevent_fd readable. | |
| #define | TEVENT_FD_WANTERROR(fde) |
| Convenience function for declaring a tevent_fd waiting for errors. | |
| #define | TEVENT_FD_NOT_WRITEABLE(fde) |
| Convenience function for declaring a tevent_fd non-writable. | |
| #define | TEVENT_FD_NOT_READABLE(fde) |
| Convenience function for declaring a tevent_fd non-readable. | |
| #define | TEVENT_FD_NOT_WANTERROR(fde) |
| Convenience function for declaring a tevent_fd not waiting for errors. | |
Typedefs | |
| typedef void(* | tevent_fd_handler_t) (struct tevent_context *ev, struct tevent_fd *fde, uint16_t flags, void *private_data) |
| Called when a file descriptor monitored by tevent has data to be read or written on it. | |
| typedef void(* | tevent_fd_close_fn_t) (struct tevent_context *ev, struct tevent_fd *fde, int fd, void *private_data) |
| Called when tevent is ceasing the monitoring of a file descriptor. | |
| typedef void(* | tevent_timer_handler_t) (struct tevent_context *ev, struct tevent_timer *te, struct timeval current_time, void *private_data) |
| Called when a tevent timer has fired. | |
| typedef void(* | tevent_immediate_handler_t) (struct tevent_context *ctx, struct tevent_immediate *im, void *private_data) |
| Called when a tevent immediate event is invoked. | |
| typedef void(* | tevent_signal_handler_t) (struct tevent_context *ev, struct tevent_signal *se, int signum, int count, void *siginfo, void *private_data) |
| Called after tevent detects the specified signal. | |
| typedef void(* | tevent_debug_fn) (void *context, enum tevent_debug_level level, const char *fmt, va_list ap) |
| The tevent debug callbac. | |
Enumerations | |
| enum | tevent_debug_level |
| Debug level of tevent. | |
| enum | tevent_trace_point { TEVENT_TRACE_BEFORE_WAIT , TEVENT_TRACE_AFTER_WAIT , TEVENT_TRACE_BEFORE_LOOP_ONCE , TEVENT_TRACE_AFTER_LOOP_ONCE } |
| enum | tevent_event_trace_point { TEVENT_EVENT_TRACE_ATTACH , TEVENT_EVENT_TRACE_DETACH , TEVENT_EVENT_TRACE_BEFORE_HANDLER } |
Functions | |
| struct tevent_context * | tevent_context_init (TALLOC_CTX *mem_ctx) |
| Create a event_context structure. | |
| struct tevent_context * | tevent_context_init_byname (TALLOC_CTX *mem_ctx, const char *name) |
| Create a event_context structure and select a specific backend. | |
| struct tevent_context * | tevent_context_init_ops (TALLOC_CTX *mem_ctx, const struct tevent_ops *ops, void *additional_data) |
| Create a custom event context. | |
| const char ** | tevent_backend_list (TALLOC_CTX *mem_ctx) |
| List available backends. | |
| void | tevent_set_default_backend (const char *backend) |
| Set the default tevent backend. | |
| uint32_t | tevent_context_set_wait_timeout (struct tevent_context *ev, uint32_t secs) |
| Set the default time to wait without tevent_timers pending. | |
| struct tevent_fd * | tevent_add_fd (struct tevent_context *ev, TALLOC_CTX *mem_ctx, int fd, uint16_t flags, tevent_fd_handler_t handler, void *private_data) |
| Add a file descriptor based event. | |
| void | tevent_fd_set_tag (struct tevent_fd *fde, uint64_t tag) |
| Associate a custom tag with the event. | |
| uint64_t | tevent_fd_get_tag (const struct tevent_fd *fde) |
| Get custom event tag. | |
| struct tevent_timer * | tevent_add_timer (struct tevent_context *ev, TALLOC_CTX *mem_ctx, struct timeval next_event, tevent_timer_handler_t handler, void *private_data) |
| Add a timed event. | |
| void | tevent_update_timer (struct tevent_timer *te, struct timeval next_event) |
| Set the time a tevent_timer fires. | |
| void | tevent_timer_set_tag (struct tevent_timer *te, uint64_t tag) |
| Associate a custom tag with the event. | |
| uint64_t | tevent_timer_get_tag (const struct tevent_timer *te) |
| Get custom event tag. | |
| struct tevent_immediate * | tevent_create_immediate (TALLOC_CTX *mem_ctx) |
| Initialize an immediate event object. | |
| void | tevent_schedule_immediate (struct tevent_immediate *im, struct tevent_context *ctx, tevent_immediate_handler_t handler, void *private_data) |
| Schedule an event for immediate execution. | |
| void | tevent_reset_immediate (struct tevent_immediate *im) |
| Reset an event for immediate execution. | |
| void | tevent_immediate_set_tag (struct tevent_immediate *im, uint64_t tag) |
| Associate a custom tag with the event. | |
| uint64_t | tevent_immediate_get_tag (const struct tevent_immediate *fde) |
| Get custom event tag. | |
| struct tevent_signal * | tevent_add_signal (struct tevent_context *ev, TALLOC_CTX *mem_ctx, int signum, int sa_flags, tevent_signal_handler_t handler, void *private_data) |
| Add a tevent signal handler. | |
| void | tevent_signal_set_tag (struct tevent_signal *se, uint64_t tag) |
| Associate a custom tag with the event. | |
| uint64_t | tevent_signal_get_tag (const struct tevent_signal *se) |
| Get custom event tag. | |
| size_t | tevent_num_signals (void) |
| the number of supported signals | |
| size_t | tevent_sa_info_queue_count (void) |
| the number of pending realtime signals | |
| int | tevent_loop_once (struct tevent_context *ev) |
| Pass a single time through the mainloop. | |
| int | tevent_loop_wait (struct tevent_context *ev) |
| Run the mainloop. | |
| void | tevent_fd_set_close_fn (struct tevent_fd *fde, tevent_fd_close_fn_t close_fn) |
| Assign a function to run when a tevent_fd is freed. | |
| void | tevent_fd_set_auto_close (struct tevent_fd *fde) |
| Automatically close the file descriptor when the tevent_fd is freed. | |
| uint16_t | tevent_fd_get_flags (struct tevent_fd *fde) |
| Return the flags set on this file descriptor event. | |
| void | tevent_fd_set_flags (struct tevent_fd *fde, uint16_t flags) |
| Set flags on a file descriptor event. | |
| bool | tevent_signal_support (struct tevent_context *ev) |
| Query whether tevent supports signal handling. | |
| int | tevent_set_debug (struct tevent_context *ev, tevent_debug_fn debug, void *context) |
| Set destination for tevent debug messages. | |
| enum tevent_debug_level | tevent_set_max_debug_level (struct tevent_context *ev, enum tevent_debug_level max_level) |
| Set maximum debug level for tevent debug messages. | |
| int | tevent_set_debug_stderr (struct tevent_context *ev) |
| Designate stderr for debug message output. | |
| void | tevent_set_trace_callback (struct tevent_context *ev, tevent_trace_callback_t cb, void *private_data) |
| Register a callback to be called at certain trace points. | |
| void | tevent_get_trace_callback (struct tevent_context *ev, tevent_trace_callback_t *cb, void *private_data) |
| Retrieve the current trace callback. | |
| void | tevent_set_trace_fd_callback (struct tevent_context *ev, tevent_trace_fd_callback_t cb, void *private_data) |
| Register a callback to be called at certain trace points of fd event. | |
| void | tevent_get_trace_fd_callback (struct tevent_context *ev, tevent_trace_fd_callback_t *cb, void *p_private_data) |
| Retrieve the current trace callback of file descriptor event. | |
| void | tevent_set_trace_signal_callback (struct tevent_context *ev, tevent_trace_signal_callback_t cb, void *private_data) |
| Register a callback to be called at certain trace points of signal event. | |
| void | tevent_get_trace_signal_callback (struct tevent_context *ev, tevent_trace_signal_callback_t *cb, void *p_private_data) |
| Retrieve the current trace callback of signal event. | |
| void | tevent_set_trace_timer_callback (struct tevent_context *ev, tevent_trace_timer_callback_t cb, void *private_data) |
| Register a callback to be called at certain trace points of timer event. | |
| void | tevent_get_trace_timer_callback (struct tevent_context *ev, tevent_trace_timer_callback_t *cb, void *p_private_data) |
| Retrieve the current trace callback of timer event. | |
| void | tevent_set_trace_immediate_callback (struct tevent_context *ev, tevent_trace_immediate_callback_t cb, void *private_data) |
| Register a callback to be called at certain trace points of immediate event. | |
| void | tevent_get_trace_immediate_callback (struct tevent_context *ev, tevent_trace_immediate_callback_t *cb, void *p_private_data) |
| Retrieve the current trace callback of immediate event. | |
The tevent low-level API.
This API provides the public interface to manage events in the tevent mainloop. Functions are provided for managing low-level events such as timer events, fd events and signal handling.
| #define TEVENT_FD_ERROR 4 |
Monitor a file descriptor for errors.
Note: we map this from/to POLLHUP, POLLERR and where available POLLRDHUP
| #define TEVENT_FD_READ 1 |
Monitor a file descriptor for data to be read and errors.
Note: we map this from/to POLLIN, POLLHUP, POLLERR and where available POLLRDHUP
| #define TEVENT_FD_WRITE 2 |
Monitor a file descriptor for writeability.
Note: we map this from/to POLLOUT
| typedef void(* tevent_debug_fn) (void *context, enum tevent_debug_level level, const char *fmt, va_list ap) |
The tevent debug callbac.
| [in] | context | The memory context to use. |
| [in] | level | The debug level. |
| [in] | fmt | The format string. |
| [in] | ap | The arguments for the format string. |
| enum tevent_trace_point |
| struct tevent_fd * tevent_add_fd | ( | struct tevent_context * | ev, |
| TALLOC_CTX * | mem_ctx, | ||
| int | fd, | ||
| uint16_t | flags, | ||
| tevent_fd_handler_t | handler, | ||
| void * | private_data ) |
Add a file descriptor based event.
| [in] | ev | The event context to work on. |
| [in] | mem_ctx | The talloc memory context to use. |
| [in] | fd | The file descriptor to base the event on. |
| [in] | flags | TEVENT_FD_READ, TEVENT_FD_WRITE or TEVENT_FD_ERROR. |
| [in] | handler | The callback handler for the event. |
| [in] | private_data | The private data passed to the callback handler. |
| struct tevent_signal * tevent_add_signal | ( | struct tevent_context * | ev, |
| TALLOC_CTX * | mem_ctx, | ||
| int | signum, | ||
| int | sa_flags, | ||
| tevent_signal_handler_t | handler, | ||
| void * | private_data ) |
Add a tevent signal handler.
tevent_add_signal() creates a new event for handling a signal the next time through the mainloop. It implements a very simple traditional signal handler whose only purpose is to add the handler event into the mainloop.
| [in] | ev | The event context to work on. |
| [in] | mem_ctx | The talloc memory context to use. |
| [in] | signum | The signal to trap |
| [in] | handler | The callback handler for the signal. |
| [in] | sa_flags | sigaction flags for this signal handler. |
| [in] | private_data | The private data passed to the callback handler. |
| struct tevent_timer * tevent_add_timer | ( | struct tevent_context * | ev, |
| TALLOC_CTX * | mem_ctx, | ||
| struct timeval | next_event, | ||
| tevent_timer_handler_t | handler, | ||
| void * | private_data ) |
Add a timed event.
| [in] | ev | The event context to work on. |
| [in] | mem_ctx | The talloc memory context to use. |
| [in] | next_event | Timeval specifying the absolute time to fire this event. This is not an offset. |
| [in] | handler | The callback handler for the event. |
| [in] | private_data | The private data passed to the callback handler. |
| const char ** tevent_backend_list | ( | TALLOC_CTX * | mem_ctx | ) |
List available backends.
| [in] | mem_ctx | The memory context to use. |
| struct tevent_context * tevent_context_init | ( | TALLOC_CTX * | mem_ctx | ) |
Create a event_context structure.
This must be the first events call, and all subsequent calls pass this event_context as the first element. Event handlers also receive this as their first argument.
| [in] | mem_ctx | The memory context to use. |
| struct tevent_context * tevent_context_init_byname | ( | TALLOC_CTX * | mem_ctx, |
| const char * | name ) |
Create a event_context structure and select a specific backend.
This must be the first events call, and all subsequent calls pass this event_context as the first element. Event handlers also receive this as their first argument.
| [in] | mem_ctx | The memory context to use. |
| [in] | name | The name of the backend to use. |
| struct tevent_context * tevent_context_init_ops | ( | TALLOC_CTX * | mem_ctx, |
| const struct tevent_ops * | ops, | ||
| void * | additional_data ) |
Create a custom event context.
| [in] | mem_ctx | The memory context to use. |
| [in] | ops | The function pointer table of the backend. |
| [in] | additional_data | The additional/private data to this instance |
| uint32_t tevent_context_set_wait_timeout | ( | struct tevent_context * | ev, |
| uint32_t | secs ) |
Set the default time to wait without tevent_timers pending.
Setting the wait timeout to 0 means polling behaviour, e.g. tevent_loop_once will return -1/errno=EAGAIN, when all currently available events were processes.
Setting it to UINT32_MAX makes tevent_loop_once wait forever. The default is 30 seconds.
| [in] | ev | The tevent context to set this on |
| [in] | secs | The number of seconds to wait without timers |
| struct tevent_immediate * tevent_create_immediate | ( | TALLOC_CTX * | mem_ctx | ) |
Initialize an immediate event object.
This object can be used to trigger an event to occur immediately after returning from the current event (before any other event occurs)
| [in] | mem_ctx | The talloc memory context to use as the parent |
| uint16_t tevent_fd_get_flags | ( | struct tevent_fd * | fde | ) |
Return the flags set on this file descriptor event.
| [in] | fde | File descriptor event to query |
| void tevent_fd_set_auto_close | ( | struct tevent_fd * | fde | ) |
Automatically close the file descriptor when the tevent_fd is freed.
This function calls close(fd) internally.
| [in] | fde | File descriptor event to auto-close |
| void tevent_fd_set_close_fn | ( | struct tevent_fd * | fde, |
| tevent_fd_close_fn_t | close_fn ) |
Assign a function to run when a tevent_fd is freed.
This function is a destructor for the tevent_fd. It does not automatically close the file descriptor. If this is the desired behavior, then it must be performed by the close_fn.
| [in] | fde | File descriptor event on which to set the destructor |
| [in] | close_fn | Destructor to execute when fde is freed |
| void tevent_fd_set_flags | ( | struct tevent_fd * | fde, |
| uint16_t | flags ) |
Set flags on a file descriptor event.
| [in] | fde | File descriptor event to set |
| [in] | flags | Flags to set on the event. See TEVENT_FD_READ, TEVENT_FD_WRITE and TEVENT_FD_ERROR |
| void tevent_fd_set_tag | ( | struct tevent_fd * | fde, |
| uint64_t | tag ) |
Associate a custom tag with the event.
This tag can be then retrieved with tevent_fd_get_tag()
| [in] | fde | The file descriptor event. |
| [in] | tag | Custom tag. |
| void tevent_get_trace_callback | ( | struct tevent_context * | ev, |
| tevent_trace_callback_t * | cb, | ||
| void * | private_data ) |
Retrieve the current trace callback.
| [in] | ev | Event context |
| [out] | cb | Registered trace callback |
| [out] | private_data | Registered data to be passed to callback |
| void tevent_get_trace_fd_callback | ( | struct tevent_context * | ev, |
| tevent_trace_fd_callback_t * | cb, | ||
| void * | p_private_data ) |
Retrieve the current trace callback of file descriptor event.
| [in] | ev | Event context |
| [out] | cb | Registered trace callback |
| [out] | p_private_data | Registered data to be passed to callback |
| void tevent_get_trace_immediate_callback | ( | struct tevent_context * | ev, |
| tevent_trace_immediate_callback_t * | cb, | ||
| void * | p_private_data ) |
Retrieve the current trace callback of immediate event.
| [in] | ev | Event context |
| [out] | cb | Registered trace callback |
| [out] | p_private_data | Registered data to be passed to callback |
| void tevent_get_trace_signal_callback | ( | struct tevent_context * | ev, |
| tevent_trace_signal_callback_t * | cb, | ||
| void * | p_private_data ) |
Retrieve the current trace callback of signal event.
| [in] | ev | Event context |
| [out] | cb | Registered trace callback |
| [out] | p_private_data | Registered data to be passed to callback |
| void tevent_get_trace_timer_callback | ( | struct tevent_context * | ev, |
| tevent_trace_timer_callback_t * | cb, | ||
| void * | p_private_data ) |
Retrieve the current trace callback of timer event.
| [in] | ev | Event context |
| [out] | cb | Registered trace callback |
| [out] | p_private_data | Registered data to be passed to callback |
| void tevent_immediate_set_tag | ( | struct tevent_immediate * | im, |
| uint64_t | tag ) |
Associate a custom tag with the event.
This tag can be then retrieved with tevent_immediate_get_tag()
| [in] | im | The immediate event. |
| [in] | tag | Custom tag. |
| int tevent_loop_once | ( | struct tevent_context * | ev | ) |
Pass a single time through the mainloop.
This will process any appropriate signal, immediate, fd and timer events
| [in] | ev | The event context to process |
| int tevent_loop_wait | ( | struct tevent_context * | ev | ) |
Run the mainloop.
The mainloop will run until there are no events remaining to be processed
| [in] | ev | The event context to process |
| size_t tevent_num_signals | ( | void | ) |
the number of supported signals
This returns value of the configure time TEVENT_NUM_SIGNALS constant.
The 'signum' argument of tevent_add_signal() must be less than TEVENT_NUM_SIGNALS.
| void tevent_reset_immediate | ( | struct tevent_immediate * | im | ) |
Reset an event for immediate execution.
Undo the effect of tevent_schedule_immediate().
| [in] | im | The tevent_immediate object to clear the handler |
| size_t tevent_sa_info_queue_count | ( | void | ) |
the number of pending realtime signals
This returns value of TEVENT_SA_INFO_QUEUE_COUNT.
The tevent internals remember the last TEVENT_SA_INFO_QUEUE_COUNT siginfo_t structures for SA_SIGINFO signals. If the system generates more some signals get lost.
| void tevent_schedule_immediate | ( | struct tevent_immediate * | im, |
| struct tevent_context * | ctx, | ||
| tevent_immediate_handler_t | handler, | ||
| void * | private_data ) |
Schedule an event for immediate execution.
This event will occur immediately after returning from the current event (before any other event occurs)
| [in] | im | The tevent_immediate object to populate and use |
| [in] | ctx | The tevent_context to run this event |
| [in] | handler | The event handler to run when this event fires |
| [in] | private_data | Data to pass to the event handler |
| int tevent_set_debug | ( | struct tevent_context * | ev, |
| tevent_debug_fn | debug, | ||
| void * | context ) |
Set destination for tevent debug messages.
As of version 0.15.0 the invocation of the debug function for individual messages is limited by the current max_debug_level, which means TEVENT_DEBUG_TRACE messages are not passed by default:
| [in] | ev | Event context to debug |
| [in] | debug | Function to handle output printing |
| [in] | context | The context to pass to the debug function. |
| int tevent_set_debug_stderr | ( | struct tevent_context * | ev | ) |
Designate stderr for debug message output.
| [in] | ev | Event context to debug |
| void tevent_set_default_backend | ( | const char * | backend | ) |
Set the default tevent backend.
| [in] | backend | The name of the backend to set. |
| enum tevent_debug_level tevent_set_max_debug_level | ( | struct tevent_context * | ev, |
| enum tevent_debug_level | max_level ) |
Set maximum debug level for tevent debug messages.
| [in] | ev | Event context to debug |
| [in] | max_level | Function to handle output printing |
| void tevent_set_trace_callback | ( | struct tevent_context * | ev, |
| tevent_trace_callback_t | cb, | ||
| void * | private_data ) |
Register a callback to be called at certain trace points.
| [in] | ev | Event context |
| [in] | cb | Trace callback |
| [in] | private_data | Data to be passed to callback |
| void tevent_set_trace_fd_callback | ( | struct tevent_context * | ev, |
| tevent_trace_fd_callback_t | cb, | ||
| void * | private_data ) |
Register a callback to be called at certain trace points of fd event.
| [in] | ev | Event context |
| [in] | cb | Trace callback |
| [in] | private_data | Data to be passed to callback |
| void tevent_set_trace_immediate_callback | ( | struct tevent_context * | ev, |
| tevent_trace_immediate_callback_t | cb, | ||
| void * | private_data ) |
Register a callback to be called at certain trace points of immediate event.
| [in] | ev | Event context |
| [in] | cb | Trace callback |
| [in] | private_data | Data to be passed to callback |
| void tevent_set_trace_signal_callback | ( | struct tevent_context * | ev, |
| tevent_trace_signal_callback_t | cb, | ||
| void * | private_data ) |
Register a callback to be called at certain trace points of signal event.
| [in] | ev | Event context |
| [in] | cb | Trace callback |
| [in] | private_data | Data to be passed to callback |
| void tevent_set_trace_timer_callback | ( | struct tevent_context * | ev, |
| tevent_trace_timer_callback_t | cb, | ||
| void * | private_data ) |
Register a callback to be called at certain trace points of timer event.
| [in] | ev | Event context |
| [in] | cb | Trace callback |
| [in] | private_data | Data to be passed to callback |
| void tevent_signal_set_tag | ( | struct tevent_signal * | se, |
| uint64_t | tag ) |
Associate a custom tag with the event.
This tag can be then retrieved with tevent_signal_get_tag()
| [in] | fde | The signal event. |
| [in] | tag | Custom tag. |
| bool tevent_signal_support | ( | struct tevent_context * | ev | ) |
Query whether tevent supports signal handling.
| [in] | ev | An initialized tevent context |
| void tevent_timer_set_tag | ( | struct tevent_timer * | te, |
| uint64_t | tag ) |
Associate a custom tag with the event.
This tag can be then retrieved with tevent_timer_get_tag()
| [in] | te | The timer event. |
| [in] | tag | Custom tag. |
| void tevent_update_timer | ( | struct tevent_timer * | te, |
| struct timeval | next_event ) |
Set the time a tevent_timer fires.
| [in] | te | The timer event to reset |
| [in] | next_event | Timeval specifying the absolute time to fire this event. This is not an offset. |