The tevent low-level API. More...

Modules
	The tevent request functions.
	A tevent_req represents an asynchronous computation.

	The tevent helper functions

	The tevent queue functions
	A tevent_queue is used to queue up async requests that must be serialized.

	The tevent operation functions
	The following structure and registration functions are exclusively needed for people writing and pluggin a different event engine.

	The tevent compatibility functions
	The following definitions are usueful only for compatibility with the implementation originally developed within the samba4 code and will be soon removed.

Macros
#define	TEVENT_FD_READ 1
	Monitor a file descriptor for data to be read.

#define	TEVENT_FD_WRITE 2
	Monitor a file descriptor for writeability.

#define	TEVENT_FD_WRITEABLE(fde) tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) \| TEVENT_FD_WRITE)
	Convenience function for declaring a tevent_fd writable.

#define	TEVENT_FD_READABLE(fde) tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) \| TEVENT_FD_READ)
	Convenience function for declaring a tevent_fd readable.

#define	TEVENT_FD_NOT_WRITEABLE(fde) tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
	Convenience function for declaring a tevent_fd non-writable.

#define	TEVENT_FD_NOT_READABLE(fde) tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
	Convenience function for declaring a tevent_fd non-readable.

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. More...

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 }

Functions
struct tevent_context *	tevent_context_init (TALLOC_CTX *mem_ctx)
	Create a event_context structure. More...

struct tevent_context *	tevent_context_init_byname (TALLOC_CTX mem_ctx, const char name)
	Create a event_context structure and select a specific backend. More...

struct tevent_context *	tevent_context_init_ops (TALLOC_CTX mem_ctx, const struct tevent_ops ops, void *additional_data)
	Create a custom event context. More...

const char **	tevent_backend_list (TALLOC_CTX *mem_ctx)
	List available backends. More...

void	tevent_set_default_backend (const char *backend)
	Set the default tevent backend. More...

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. More...

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. More...

void	tevent_update_timer (struct tevent_timer *te, struct timeval next_event)
	Set the time a tevent_timer fires. More...

struct tevent_immediate *	tevent_create_immediate (TALLOC_CTX *mem_ctx)
	Initialize an immediate event object. More...

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. More...

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. More...

size_t	tevent_num_signals (void)
	the number of supported signals More...

size_t	tevent_sa_info_queue_count (void)
	the number of pending realtime signals More...

int	tevent_loop_once (struct tevent_context *ev)
	Pass a single time through the mainloop. More...

int	tevent_loop_wait (struct tevent_context *ev)
	Run the mainloop. More...

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. More...

void	tevent_fd_set_auto_close (struct tevent_fd *fde)
	Automatically close the file descriptor when the tevent_fd is freed. More...

uint16_t	tevent_fd_get_flags (struct tevent_fd *fde)
	Return the flags set on this file descriptor event. More...

void	tevent_fd_set_flags (struct tevent_fd *fde, uint16_t flags)
	Set flags on a file descriptor event. More...

bool	tevent_signal_support (struct tevent_context *ev)
	Query whether tevent supports signal handling. More...

int	tevent_set_debug (struct tevent_context ev, tevent_debug_fn debug, void context)
	Set destination for tevent debug messages. More...

int	tevent_set_debug_stderr (struct tevent_context *ev)
	Designate stderr for debug message output. More...

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. More...

void	tevent_get_trace_callback (struct tevent_context ev, tevent_trace_callback_t cb, void *private_data)
	Retrieve the current trace callback. More...

Detailed Description

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.

Typedef Documentation

§ tevent_debug_fn

typedef void(* tevent_debug_fn) (void *context, enum tevent_debug_level level, const char *fmt, va_list ap)

The tevent debug callbac.

Parameters

[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.

Enumeration Type Documentation

§ tevent_trace_point

enum tevent_trace_point

Enumerator
TEVENT_TRACE_BEFORE_WAIT	Corresponds to a trace point just before waiting.
TEVENT_TRACE_AFTER_WAIT	Corresponds to a trace point just after waiting.
TEVENT_TRACE_BEFORE_LOOP_ONCE	Corresponds to a trace point just before calling the loop_once() backend function.
TEVENT_TRACE_AFTER_LOOP_ONCE	Corresponds to a trace point right after the loop_once() backend function has returned.

Function Documentation

§ tevent_add_fd()

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.

Parameters

[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 or TEVENT_FD_WRITE
[in]	handler	The callback handler for the event.
[in]	private_data	The private data passed to the callback handler.

Returns: The file descriptor based event, NULL on error.

Note: To cancel the monitoring of a file descriptor, call talloc_free() on the object returned by this function.; The caller should avoid closing the file descriptor before calling talloc_free()! Otherwise the behaviour is undefined which might result in crashes. See https://bugzilla.samba.org/show_bug.cgi?id=11141 for an example.

§ tevent_add_signal()

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.

Parameters

[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.

Returns: The newly-created signal handler event, or NULL on error.

Note: To cancel a signal handler, call talloc_free() on the event returned from this function.

See also: tevent_num_signals, tevent_sa_info_queue_count

§ tevent_add_timer()

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.

Parameters

[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.

Returns: The newly-created timer event, or NULL on error.

Note: To cancel a timer event before it fires, call talloc_free() on the event returned from this function. This event is automatically talloc_free()-ed after its event handler files, if it hasn't been freed yet.; Unlike some mainloops, tevent timers are one-time events. To set up a recurring event, it is necessary to call tevent_add_timer() again during the handler processing.; Due to the internal mainloop processing, a timer set to run immediately will do so after any other pending timers fire, but before any further file descriptor or signal handling events fire. Callers should not rely on this behavior!

§ tevent_backend_list()

const char** tevent_backend_list ( TALLOC_CTX * mem_ctx )

List available backends.

Parameters

[in] mem_ctx The memory context to use.

Returns: A string vector with a terminating NULL element, NULL on error.

§ tevent_context_init()

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.

Parameters

[in] mem_ctx The memory context to use.

Returns: An allocated tevent context, NULL on error.

See also: tevent_context_init()

§ tevent_context_init_byname()

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.

Parameters

[in]	mem_ctx	The memory context to use.
[in]	name	The name of the backend to use.

Returns: An allocated tevent context, NULL on error.

§ tevent_context_init_ops()

struct tevent_context* tevent_context_init_ops	(	TALLOC_CTX *	mem_ctx,
		const struct tevent_ops *	ops,
		void *	additional_data
	)

Create a custom event context.

Parameters

[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

Returns: An allocated tevent context, NULL on error.

§ tevent_create_immediate()

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)

Parameters

[in] mem_ctx The talloc memory context to use as the parent

Returns: An empty tevent_immediate object. Use tevent_schedule_immediate to populate and use it.

Note: Available as of tevent 0.9.8

§ tevent_fd_get_flags()

uint16_t tevent_fd_get_flags ( struct tevent_fd * fde )

Return the flags set on this file descriptor event.

Parameters

[in] fde File descriptor event to query

Returns: The flags set on the event. See TEVENT_FD_READ and TEVENT_FD_WRITE

§ tevent_fd_set_auto_close()

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.

Parameters

[in] fde File descriptor event to auto-close

§ tevent_fd_set_close_fn()

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.

Parameters

[in]	fde	File descriptor event on which to set the destructor
[in]	close_fn	Destructor to execute when fde is freed

§ tevent_fd_set_flags()

void tevent_fd_set_flags	(	struct tevent_fd *	fde,
		uint16_t	flags
	)

Set flags on a file descriptor event.

Parameters

[in]	fde	File descriptor event to set
[in]	flags	Flags to set on the event. See TEVENT_FD_READ and TEVENT_FD_WRITE

§ tevent_get_trace_callback()

void tevent_get_trace_callback	(	struct tevent_context *	ev,
		tevent_trace_callback_t *	cb,
		void *	private_data
	)

Retrieve the current trace callback.

Parameters

[in]	ev	Event context
[out]	cb	Registered trace callback
[out]	private_data	Registered data to be passed to callback

Note: This can be used to allow one component that wants to register a callback to respect the callback that another component has already registered.

§ tevent_loop_once()

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

Parameters

[in] ev The event context to process

Returns: Zero on success, nonzero if an internal error occurred

§ tevent_loop_wait()

int tevent_loop_wait ( struct tevent_context * ev )

Run the mainloop.

The mainloop will run until there are no events remaining to be processed

Parameters

[in] ev The event context to process

Returns: Zero if all events have been processed. Nonzero if an internal error occurred.

§ tevent_num_signals()

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.

See also: tevent_add_signal

§ tevent_sa_info_queue_count()

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.

See also: tevent_add_signal

§ tevent_schedule_immediate()

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)

Parameters

[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

§ tevent_set_debug()

int tevent_set_debug	(	struct tevent_context *	ev,
		tevent_debug_fn	debug,
		void *	context
	)

Set destination for tevent debug messages.

Parameters

[in]	ev	Event context to debug
[in]	debug	Function to handle output printing
[in]	context	The context to pass to the debug function.

Returns: Always returns 0 as of version 0.9.8

Note: Default is to emit no debug messages

§ tevent_set_debug_stderr()

int tevent_set_debug_stderr ( struct tevent_context * ev )

Designate stderr for debug message output.

Parameters

[in] ev Event context to debug

Note: This function will only output TEVENT_DEBUG_FATAL, TEVENT_DEBUG_ERROR and TEVENT_DEBUG_WARNING messages. For TEVENT_DEBUG_TRACE, please define a function for tevent_set_debug()

§ tevent_set_default_backend()

void tevent_set_default_backend ( const char * backend )

Set the default tevent backend.

Parameters

[in] backend The name of the backend to set.

§ tevent_set_trace_callback()

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.

Parameters

[in]	ev	Event context
[in]	cb	Trace callback
[in]	private_data	Data to be passed to callback

Note: The callback will be called at trace points defined by tevent_trace_point. Call with NULL to reset.

§ tevent_signal_support()

bool tevent_signal_support ( struct tevent_context * ev )

Query whether tevent supports signal handling.

Parameters

[in] ev An initialized tevent context

Returns: True if this platform and tevent context support signal handling

§ tevent_update_timer()

void tevent_update_timer	(	struct tevent_timer *	te,
		struct timeval	next_event
	)

Set the time a tevent_timer fires.

Parameters

[in]	te	The timer event to reset
[in]	next_event	Timeval specifying the absolute time to fire this event. This is not an offset.

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

§ tevent_debug_fn

Enumeration Type Documentation

§ tevent_trace_point

Function Documentation

§ tevent_add_fd()

§ tevent_add_signal()

§ tevent_add_timer()

§ tevent_backend_list()

§ tevent_context_init()

§ tevent_context_init_byname()

§ tevent_context_init_ops()

§ tevent_create_immediate()

§ tevent_fd_get_flags()

§ tevent_fd_set_auto_close()

§ tevent_fd_set_close_fn()

§ tevent_fd_set_flags()

§ tevent_get_trace_callback()

§ tevent_loop_once()

§ tevent_loop_wait()

§ tevent_num_signals()

§ tevent_sa_info_queue_count()

§ tevent_schedule_immediate()

§ tevent_set_debug()

§ tevent_set_debug_stderr()

§ tevent_set_default_backend()

§ tevent_set_trace_callback()

§ tevent_signal_support()

§ tevent_update_timer()