Event loop extension functions

Data Structures
struct	getdns_eventloop_event
struct	getdns_eventloop
struct	getdns_eventloop_vmt

Typedefs
typedef void(*	getdns_eventloop_callback) (void *userarg)
typedef struct getdns_eventloop_event	getdns_eventloop_event
typedef struct getdns_eventloop_vmt	getdns_eventloop_vmt
typedef struct getdns_eventloop	getdns_eventloop
typedef void(*	getdns_eventloop_noargs) (getdns_eventloop *loop)
typedef getdns_return_t(*	getdns_eventloop_schedule) (getdns_eventloop *loop, int fd, uint64_t timeout, getdns_eventloop_event *ev)
typedef getdns_return_t(*	getdns_eventloop_clear) (getdns_eventloop *loop, getdns_eventloop_event *ev)
typedef void(*	getdns_eventloop_run_once) (getdns_eventloop *loop, int blocking)

Functions
getdns_return_t	getdns_extension_set_libev_loop (struct getdns_context *context, struct ev_loop *ev_loop)
getdns_return_t	getdns_extension_set_libevent_base (struct getdns_context *context, struct event_base *this_event_base)
getdns_return_t	getdns_extension_set_libuv_loop (struct getdns_context *context, struct uv_loop_s *uv_loop)
getdns_return_t	getdns_context_set_eventloop (getdns_context *context, getdns_eventloop *eventloop)
getdns_return_t	getdns_context_get_eventloop (const getdns_context *context, getdns_eventloop **eventloop)
void	getdns_context_run (getdns_context *context)

Detailed Description

Typedef Documentation

getdns_eventloop_callback

typedef void(* getdns_eventloop_callback) (void *userarg)

The type of callback function that is used by the callbacks in an getdns_eventloop_event.

Parameters

userarg

This will have the value of the userarg attribute of the getdns_eventloop_event struct in which this callback was present.

Definition at line 202 of file getdns_extra.h.

getdns_eventloop_event

typedef struct getdns_eventloop_event getdns_eventloop_event

Definition at line 202 of file getdns_extra.h.

getdns_eventloop_vmt

typedef struct getdns_eventloop_vmt getdns_eventloop_vmt

Definition at line 202 of file getdns_extra.h.

getdns_eventloop

typedef struct getdns_eventloop getdns_eventloop

The manifestation of the event loop abstraction layer. Event loop extension implementers should extend this with attributed needed for the underlying event loop. The current event loop extension can be obtained with the getdns_context_get_eventloop() function.

getdns_eventloop_noargs

typedef void(* getdns_eventloop_noargs) (getdns_eventloop *loop)

The function prototype for the cleanup and run functions in an getdns event loop's Virtual Method Table. These methods have no (extra) arguments and return nothing.

Parameters

loop	The event loop to run or cleanup

Definition at line 270 of file getdns_extra.h.

getdns_eventloop_schedule

typedef getdns_return_t(* getdns_eventloop_schedule) (getdns_eventloop *loop, int fd, uint64_t timeout, getdns_eventloop_event *ev)

The function prototype for the schedule function in an event loop Virtual Method Table. The getdns_eventloop_event must be provided by the caller with the callbacks and userarg therein already supplied (by the caller). This function will set the ev pointer (in the getdns_eventloop_event) to refer to the underlying (extension) event.

Parameters

loop	The event loop for which to register the event.
fd	The file descriptor for which to schedule the read_cb and/or write_cb callbacks.
timeout	The number of milliseconds that must pass without read and/or write event after which the timeout_cb callback is fired.
ev	The event with all attributes provisioned, except for the ev->ev attribute, which will be provisioned by the implementation of the schedule method.

Returns

GETDNS_RETURN_GOOD when successful and an error code otherwise.

Definition at line 289 of file getdns_extra.h.

getdns_eventloop_clear

typedef getdns_return_t(* getdns_eventloop_clear) (getdns_eventloop *loop, getdns_eventloop_event *ev)

The function prototype for the clean function in an event loop Virtual Method Table. The implementation must clear the event (which is referred to with ev->ev) in the underlying event loop and make ev->ev NULL when done. getdns will test for this value to determine if events are scheduled or not.

Parameters

	loop	The event loop for which to event needs to be cleared.
[in,out]	ev	The event with the ev->ev attribute referring to the underlying event. ev->ev must be set to NULL after the event was cleared.

Returns

GETDNS_RETURN_GOOD when successful and an error code otherwise.

Definition at line 304 of file getdns_extra.h.

getdns_eventloop_run_once

typedef void(* getdns_eventloop_run_once) (getdns_eventloop *loop, int blocking)

The function prototype for the run_once function in an event loop Virtual Method Table. The implementation must do a single round of firing callbacks, either blocking or not.

Parameters

loop	The event loop to run
blocking	When 0, only callbacks for file descriptors that are immediately readable or writable or timeouts that have passed will be fired. When 1, the eventloop will wait until the first callback can be fired, either because a associated file descriptor has become readable or writeable, or because a timeout time passed.

Definition at line 319 of file getdns_extra.h.

Function Documentation

getdns_extension_set_libev_loop()

getdns_return_t getdns_extension_set_libev_loop	(	struct getdns_context *	context,
		struct ev_loop *	ev_loop
	)

Associate the libev ev_loop with the context, so that all asynchronous requests will schedule Input/Output with it. Synchronous requests will still use a default eventloop based on poll(). Applications need to

#include <getdns/getdns_ext_libev.h> 

and link with libgetdns_ext_ev to use this function. getdns needs to have been configured with –with-libev for this extension to be available.

Parameters

context	The context to configure
ev_loop	The libev event loop to associate with this context.

Returns

GETDNS_RETURN_GOOD when successful

GETDNS_RETURN_BAD_CONTEXT when context is NULL

GETDNS_RETURN_INVALID_PARAMETER when ev_loop is NULL

GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated

getdns_extension_set_libevent_base()

getdns_return_t getdns_extension_set_libevent_base	(	struct getdns_context *	context,
		struct event_base *	this_event_base
	)

Associate the libevent event_base with the context, so that all asynchronous requests will schedule Input/Output with it. Synchronous requests will still use a default eventloop based on poll(). Applications need to

#include <getdns/getdns_ext_libevent.h> 

and link with libgetdns_ext_event to use this function. getdns needs to have been configured with –with-libevent for this extension to be available.

Parameters

context	The context to configure
this_event_base	The libevent event base to associate with this context.

Returns

GETDNS_RETURN_GOOD when successful

GETDNS_RETURN_BAD_CONTEXT when context is NULL

GETDNS_RETURN_INVALID_PARAMETER when this_event_base is NULL

GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated

getdns_extension_set_libuv_loop()

getdns_return_t getdns_extension_set_libuv_loop	(	struct getdns_context *	context,
		struct uv_loop_s *	uv_loop
	)

Associate the libuv uv_loop with the context, so that all asynchronous requests will schedule Input/Output with it. Synchronous requests will still use a default eventloop based on poll(). Applications need to

#include <getdns/getdns_ext_libuv.h> 

and link with libgetdns_ext_uv to use this function. getdns needs to have been configured with –with-libuv for this extension to be available.

Parameters

context	The context to configure
uv_loop	The libuv event loop to associate with this context.

Returns

GETDNS_RETURN_GOOD when successful

GETDNS_RETURN_BAD_CONTEXT when context is NULL

GETDNS_RETURN_INVALID_PARAMETER when uv_loop is NULL

GETDNS_RETURN_MEMORY_ERROR when memory could not be allocated

getdns_context_set_eventloop()

getdns_return_t getdns_context_set_eventloop	(	getdns_context *	context,
		getdns_eventloop *	eventloop
	)

Configure a context to use the specified event loop abstraction extension. This function must be called with an provisioned eventloop by the event loop extension registration functions.

See also

getdns_context_get_eventloop

Parameters

context	The context to configure
eventloop	The event loop abstraction extension with a completely provisioned Virtual Method Table and other associated data which is opaque to the user.

Returns

GETDNS_RETURN_GOOD when successful

GETDNS_RETURN_INVALID_PARAMETER when context or eventloop were NULL.

getdns_context_get_eventloop()

getdns_return_t getdns_context_get_eventloop	(	const getdns_context *	context,
		getdns_eventloop **	eventloop
	)

Get the current event loop abstraction extension from the context Applications using getdns can use the event loop abstraction extension themselves directly to inherit the flexibility being immediately compatible with all the event loop systems for which there is an extension (i.e. libevent, libev and libuv).

See also

getdns_context_set_eventloop

Parameters

[in]	context	The context to get the eventloop from
[out]	eventloop	The currently active event loop abstraction extension

Returns

GETDNS_RETURN_GOOD when successful

GETDNS_RETURN_INVALID_PARAMETER when context or evenloop were NULL

getdns_context_run()

void getdns_context_run

(

getdns_context *

context

)

Run the context's event loop until nothing more to do. This is equivalend to:

if (getdns_context_get_eventloop(context, &loop) == GETDNS_RETURN_GOOD)
    loop->vmt->run(loop);

Parameters

context

The context which event loop to run.