watch.h File Reference

"Prepare" and "check" watchers. More...

#include <event2/visibility.h>

Go to the source code of this file.

Typedefs
typedef void(*	evwatch_check_cb) (struct evwatch *, const struct evwatch_check_cb_info *, void *)
	Check callback, invoked by event_base_loop immediately after polling for I/O and before processing any active events. More...
typedef void(*	evwatch_prepare_cb) (struct evwatch *, const struct evwatch_prepare_cb_info *, void *)
	Prepare callback, invoked by event_base_loop immediately before polling for I/O. More...

Functions
EVENT2_EXPORT_SYMBOL struct event_base *	evwatch_base (struct evwatch *watcher)
	Get the event_base that a given evwatch is registered with. More...
EVENT2_EXPORT_SYMBOL struct evwatch *	evwatch_check_new (struct event_base *base, evwatch_check_cb callback, void *arg)
	Register a new "check" watcher, to be called in the event loop after polling for events and before handling them. More...
EVENT2_EXPORT_SYMBOL void	evwatch_free (struct evwatch *watcher)
	Deregister and deallocate a watcher. More...
EVENT2_EXPORT_SYMBOL int	evwatch_prepare_get_timeout (const struct evwatch_prepare_cb_info *info, struct timeval *timeout)
	Get the timeout (the expected polling duration) passed to the underlying implementation's dispatch. More...
EVENT2_EXPORT_SYMBOL struct evwatch *	evwatch_prepare_new (struct event_base *base, evwatch_prepare_cb callback, void *arg)
	Register a new "prepare" watcher, to be called in the event loop prior to polling for events. More...

Detailed Description

"Prepare" and "check" watchers.

"Prepare" and "check" watchers. A "prepare" watcher is a callback that fires immediately before polling for I/O. A "check" watcher is a callback that fires immediately after polling and before processing any active events. This may be useful for embedding other libraries' event loops (e.g. UI toolkits) into libevent's.

Typedef Documentation

evwatch_check_cb

typedef void(* evwatch_check_cb) (struct evwatch *, const struct evwatch_check_cb_info *, void *)

Check callback, invoked by event_base_loop immediately after polling for I/O and before processing any active events.

Parameters

watcher	the check watcher that invoked this callback.
info	contextual information passed from event_base_loop.
arg	additional user-defined argument, set in evwatch_check_new.

evwatch_prepare_cb

typedef void(* evwatch_prepare_cb) (struct evwatch *, const struct evwatch_prepare_cb_info *, void *)

Prepare callback, invoked by event_base_loop immediately before polling for I/O.

Parameters

watcher	the prepare watcher that invoked this callback.
info	contextual information passed from event_base_loop.
arg	additional user-defined argument, set in evwatch_prepare_new.

Function Documentation

evwatch_base()

EVENT2_EXPORT_SYMBOL struct event_base* evwatch_base

(

struct evwatch *

watcher

)

Get the event_base that a given evwatch is registered with.

Parameters

watcher

the watcher to get the event_base for.

Returns

the event_base for the given watcher.

evwatch_check_new()

EVENT2_EXPORT_SYMBOL struct evwatch* evwatch_check_new	(	struct event_base *	base,
		evwatch_check_cb	callback,
		void *	arg
	)

Register a new "check" watcher, to be called in the event loop after polling for events and before handling them.

Watchers will be called in the order they were registered.

Parameters

base	the event_base to operate on.
callback	the callback function to invoke.
arg	additional user-defined argument provided to the callback.

Returns

a pointer to the newly allocated event watcher.

evwatch_free()

EVENT2_EXPORT_SYMBOL void evwatch_free

(

struct evwatch *

watcher

)

Deregister and deallocate a watcher.

Any watchers not freed using evwatch_free will eventually be deallocated in event_base_free (calling evwatch_free on a watcher after event_base_free has been called on its corresponding event_base is an error).

Parameters

watcher

the watcher to deregister and deallocate.

evwatch_prepare_get_timeout()

EVENT2_EXPORT_SYMBOL int evwatch_prepare_get_timeout	(	const struct evwatch_prepare_cb_info *	info,
		struct timeval *	timeout
	)

Get the timeout (the expected polling duration) passed to the underlying implementation's dispatch.

This value will only be set if there are pending EV_TIMEOUT events and if the event_base isn't in EVLOOP_NONBLOCK mode. It may be a useful performance statistic to compare the expected polling duration against the actual polling duration (that is, the time difference measured between this prepare callback and the following check callback).

Parameters

info	the "prepare" callback info.
timeout	address of a timeval to write the polling duration to.

Returns

1 if a value was written to *timeout, or 0 if not.

evwatch_prepare_new()

EVENT2_EXPORT_SYMBOL struct evwatch* evwatch_prepare_new	(	struct event_base *	base,
		evwatch_prepare_cb	callback,
		void *	arg
	)

Register a new "prepare" watcher, to be called in the event loop prior to polling for events.

Watchers will be called in the order they were registered.

Parameters

base	the event_base to operate on.
callback	the callback function to invoke.
arg	additional user-defined argument provided to the callback.

Returns

a pointer to the newly allocated event watcher.