Event loop

Functions
int	amxrt_el_create (void)
	Creates and initializes all needed event loop components. More...
int	amxrt_el_start (void)
	Starts the event loop. More...
int	amxrt_el_stop (void)
	Stops the event loop. More...
int	amxrt_el_destroy (void)
	Cleans-up the event loop components. More...

Detailed Description

A default ambiorix eventloop can be created using the event loop functions in this library. The eventloop is implemented using libevent.

In computer science, the event loop is a programming construct or design pattern that waits for and dispatches events or messages in a program. The event loop works by making a request to some internal or external "event provider" (that generally blocks the request until an event has arrived), then calls the relevant event handler ("dispatches the event"). The event loop is also sometimes referred to as the message dispatcher, message loop, message pump, or run loop.

The event-loop may be used in conjunction with a reactor, if the event provider follows the file interface, which can be selected or 'polled' (the Unix system call, not actual polling). The event loop almost always operates asynchronously with the message originator.

When the event loop forms the central control flow construct of a program, as it often does, it may be termed the main loop or main event loop. This title is appropriate, because such an event loop is at the highest level of control within the program.

When the function amxrt_el_create is called all ambiorix file descriptors (fds) are added to the eventloop for monitoring (for read), some system signals are added for monitoring.

The system signals that are monitored are:

• SIGINT - when triggered the eventloop is stopped
• SIGTERM - when triggered the eventloop is stopped
• SIGALRM - used for ambiorix timers (amxp_timer_t)

Extra system signals can be enabled using amxp_syssig_enable, or a htable list can be passed to the function amxrt_enable_syssigs. This will cause that the system signals are captured and converted to ambiorix signals. To handle them connect callback functions to them using amxp_slot_connect.

By default all opened sockets (opened with amxrt_connect) are added to the event-loop as well.

The ambiorix signals will be handled in the event loop as well. Ambiorix signals can be created using amxp_signal_emit.

For more information about ambiorix signals see libamxp.

Function Documentation

amxrt_el_create()

int amxrt_el_create

(

void

)

Creates and initializes all needed event loop components.

It is recommended to first open all needed sockets (like connections to the used bus systems), register the data model (if any), enable all system signals that needs to be handled before creating the event loop components.

Returns

0 when the event loop components are created and initialized correctly. Any other return value indicates an error.

Definition at line 253 of file amxrt_el_libevent.c.

                          {
    amxo_parser_t* parser = amxrt_get_parser();
    int retval = -1;
    struct event* event_source = NULL;
 
    base = event_base_new();
    when_null(base, leave);
 
    event_source = evsignal_new(base, SIGINT, amxrt_el_signal_cb, NULL);
    amxrt_el_add_event_source(event_source, NULL);
 
    event_source = evsignal_new(base, SIGTERM, amxrt_el_signal_cb, NULL);
    amxrt_el_add_event_source(event_source, NULL);
 
    event_source = evsignal_new(base, SIGALRM, amxrt_el_signal_timers, NULL);
    amxrt_el_add_event_source(event_source, NULL);
 
    event_source = event_new(base, amxp_signal_fd(), EV_READ | EV_PERSIST, amxrt_el_amxp_signal_read_cb, NULL);
    amxrt_el_add_event_source(event_source, NULL);
 
    event_source = event_new(base, amxp_syssig_get_fd(), EV_READ | EV_PERSIST, amxrt_el_amxp_syssignal_read_cb, NULL);
    amxrt_el_add_event_source(event_source, NULL);
 
    amxrt_el_add_read_fd(amxp_connection_get_connections());
    amxrt_el_add_read_fd(amxp_connection_get_listeners());
 
    amxp_slot_connect(NULL, "connection-added", NULL, amxrt_el_slot_add_fd, parser);
    amxp_slot_connect(NULL, "connection-wait-write", NULL, amxrt_el_slot_wait_write_fd, parser);
    amxp_slot_connect(NULL, "listen-added", NULL, amxrt_el_slot_add_fd, parser);
    amxp_slot_connect(NULL, "connection-deleted", NULL, amxrt_el_slot_remove_fd, parser);
    amxp_slot_connect(NULL, "listen-deleted", NULL, amxrt_el_slot_remove_fd, parser);
 
    retval = 0;
 
leave:
    return retval;
}

amxrt_el_destroy()

int amxrt_el_destroy

(

void

)

Cleans-up the event loop components.

When the event loop is not needed anymore, all it's components must be deleted and removed. Typically this is done just before exiting the application.

Returns

0 when everything is deleted successfully..

Definition at line 313 of file amxrt_el_libevent.c.

                           {
    amxrt_t* rt = amxrt_get();
 
    amxp_slot_disconnect(NULL, "connection-added", amxrt_el_slot_add_fd);
    amxp_slot_disconnect(NULL, "listen-added", amxrt_el_slot_add_fd);
    amxp_slot_disconnect(NULL, "connection-deleted", amxrt_el_slot_remove_fd);
 
    amxrt_el_remove_fd(amxp_connection_get_connections());
    amxrt_el_remove_fd(amxp_connection_get_listeners());
 
    amxc_llist_clean(&rt->event_sources, amxrt_el_free_event_source);
 
    if(base != NULL) {
        event_base_free(base);
        base = NULL;
    }
 
    return 0;
}

amxrt_el_start()

int amxrt_el_start

(

void

)

Starts the event loop.

This function will start the event loop. The event loop will be "waiting" for events and if one is received, it will be dispatched (correct callback functions are called).

The event loop will keep running until amxrt_el_stop is called, that is: this function will not return until the event loop is stopped.

IF the event loop fails to start the function returns immediately.

Returns

Non 0 will indicate that starting the event loop failed. 0 will indicate that the event loop was stopped.

Definition at line 291 of file amxrt_el_libevent.c.

                         {
    int retval = -1;
    amxd_dm_t* dm = amxrt_get_dm();
 
    if(base != NULL) {
        retval = event_base_dispatch(base);
    }
 
    amxp_sigmngr_trigger_signal(&dm->sigmngr, "app:stop", NULL);
    amxp_sigmngr_trigger_signal(NULL, "wait:cancel", NULL);
 
    return retval;
}

amxrt_el_stop()

int amxrt_el_stop

(

void

)

Stops the event loop.

This function will stop the event loop.

When the event loop is stopped no events will be dispatched any more.

After stopping the event loop it can be restarted by calling amxrt_el_start.

Typically an event loop is started once, and keeps on running for the complete lifetime of the application.

Returns

0 will indicate that the event loop was stopped successfully.

Definition at line 305 of file amxrt_el_libevent.c.

                        {
    int retval = -1;
    if(base != NULL) {
        retval = event_base_loopbreak(base);
    }
    return retval;
}