listeners.h

Include dependency graph for listeners.h:

Common code for port listeners.

This header defines convenient common functions to implement listeners, and should be included in platform’s sys.c.

Before including this file, define listener_event_t which represent a selectable event, as well as EventListener, which should have a list head member called listeners_list_head and a handler member called handler.

On a platform using select(3) with file descriptors, this typically is done by creating a platform_sys.h header with:

#include "sys.h"

typedef int listener_event_t;

struct EventListener
{
   struct ListHead listeners_list_head;
   event_handler_t handler;
   listener_event_t fd;
};

and by including platform_sys.h header in sys.c before listeners.h.

Functions

static void event_listener_add_to_polling_set(struct EventListener *listener, GlobalContext *glb)

Add an event listener to the set of polled events.

This function must be implemented and will typically access the platform data from glb and add the event to the set. It is called by process_listener_handler when a handler returns a new listener. It can be called by sys_register_listener. It may just set a dirty flag.

Parameters:

• listener – the listener to add to polling set

• glb – the global context

static void listener_event_remove_from_polling_set(listener_event_t event, GlobalContext *glb)

Remove an event from the set of polled events.

This function must be implemented and will typically access the platform data from glb and remove the event to the set. It is called by process_listener_handler when a handler returns NULL or a new listener. It can be called by sys_unregister_listener. It may just set a dirty flag.

Compared to event_listener_add_to_polling_set, the event listener may no longer exist if it was freed by the handler.

Parameters:

• event – the listener event to remove from polling set

• glb – the global context

static bool event_listener_is_event(EventListener *listener, listener_event_t event)

Determiner if an event is a listener’s event.

Parameters:

• listener – the listener to test

• event – the event to test

Returns:

true if event is the listener’s event

static inline bool process_listener_handler(GlobalContext *glb, listener_event_t current_event, struct ListHead *listeners, struct ListHead **item_ptr, struct ListHead **previous_ptr)

Process listener handlers, optionally in advancing order, especially useful with poll(2) which returns fd in the provided order.

Parameters:

• glb – the global context

• current_event – the selected event

• listeners – the list of listeners (locked for writing)

• item_ptr – the current cursor or NULL to search in items

• previous_ptr – the previous cursor (ignored and can be NULL if item_ptr is NULL).

Returns:

true if the current_event was found