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
userargThis 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

Definition at line 202 of file getdns_extra.h.

◆ getdns_eventloop_vmt

Definition at line 202 of file getdns_extra.h.

◆ 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
loopThe 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
loopThe event loop for which to register the event.
fdThe file descriptor for which to schedule the read_cb and/or write_cb callbacks.
timeoutThe number of milliseconds that must pass without read and/or write event after which the timeout_cb callback is fired.
evThe 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
loopThe event loop for which to event needs to be cleared.
[in,out]evThe 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
loopThe event loop to run
blockingWhen 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

Public interfaces to getdns, include in your application to use getdns API.

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
contextThe context to configure
ev_loopThe 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

Public interfaces to getdns, include in your application to use getdns API.

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
contextThe context to configure
this_event_baseThe 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

Public interfaces to getdns, include in your application to use getdns API.

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
contextThe context to configure
uv_loopThe 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
contextThe context to configure
eventloopThe 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]contextThe context to get the eventloop from
[out]eventloopThe 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:

loop->vmt->run(loop);
getdns_return_t getdns_context_get_eventloop(const getdns_context *context, getdns_eventloop **eventloop)
@ GETDNS_RETURN_GOOD
Definition: getdns.h:64
Parameters
contextThe context which event loop to run.