User manual

LwEVT is simple event manager library, its sole purpose is to be able to isolate various application modules and communicate in-between through event manager library.

Idea behind the library is to allow every module to subscribe to events or publish them upon various events or actions.

Define application events

Note

At this point we assume you have properly setup the library from Getting started guideline.

Every application is different and wants to use different types of events and its related data to be part of it. It is important to define your own lwevt_types.h application file with your events.

There are 2 methods to define the event type:

In your lwevt_types.h declare list of your application defines, as per example below. This file has to be generated by user and is application specific.

Definition of event types
1/* Define basic types */
2LWEVT_TYPE_BASIC(LWEVT_TYPE_MY_BASIC_1)
3LWEVT_TYPE_BASIC(LWEVT_TYPE_MY_BASIC_2)
4LWEVT_TYPE_BASIC(LWEVT_TYPE_MY_BASIC_3)
5
6/* Define extended types */
7LWEVT_TYPE_EXT(LWEVT_TYPE_MY_EXT_1, struct { int par1; int par2; } ext1)
8LWEVT_TYPE_EXT(LWEVT_TYPE_MY_EXT_2, struct { int par3; int par4; } ext2)
9LWEVT_TYPE_EXT(LWEVT_TYPE_MY_EXT_3, struct { int par1; int par2; } ext3)

You are now ready to send events to all subscribed modules

Produce events

Producing (sending) the event is simple and requires to fill event type and potential data (only part of extended type).

Tip

Producer does not need to be subscribed to any events.

Produce event to all subscribers
 1#include "lwevt/lwevt.h"
 2
 3void
 4produce() {
 5    lwevt_t* evt;
 6
 7    /* Initialize event management system = must be called only once in the application */
 8    lwevt_init();
 9    
10    /*
11     * Get event handle, set event data and dispatch event
12     *
13     * Send basic event - without any data
14     */
15    evt = lwevt_get_handle();
16    lwevt_dispatch(LWEVT_TYPE_MY_BASIC_1);
17
18    /*
19     * Get event handle, set event data and dispatch event
20     *
21     * Send extended event - with data
22     */
23    evt = lwevt_get_handle();
24    evt->msg.ext1.par1 = 10;    /* Some value */
25    evt->msg.ext1.par2 = 12;    /* Some value */
26    lwevt_dispatch(LWEVT_TYPE_MY_EXT_1);
27    return 0;
28}

Subscribe to events

Subscribing to events involves calling lwevt_register() function with callback function as parameter. All events are processed in the callback function from now on.

Receive events from the application
 1#include "lwevt/lwevt.h"
 2
 3/* Define event functions */
 4static void
 5prv_evt_fn(lwevt_t* e) {
 6    printf("Event type: %u\r\n", (unsigned)e->type);
 7    switch (e->type) {
 8        case LWEVT_TYPE_MY_BASIC_1: {
 9            printf("Basic event type - no data\r\n");
10            break;
11        }
12        case LWEVT_TYPE_MY_EXT_1: {
13            printf("Extended event type - with data: par1: %d, par2: %d\r\n",
14                (int)e->msg.ext1.par1, (int)e->msg.ext1.par2);
15            break;
16        }
17        default:
18            break;
19    }
20}
21
22int
23main() {
24    lwevt_t* evt;
25
26    /* Initialize event management system = must be called only once in the application  */
27    lwevt_init();
28
29    /* Set 2 custom functions for event */
30    lwevt_register(prv_evt_fn);
31
32    /* Do nothing - events are handled in callback function */
33
34    return 0;
35}

Global and local event handle

To optimize memory consumption, main event handle is defined as static global variable in the LwEVT module. It is accessible through lwevt_get_handle() function and allows use of default lwevt_dispatch() function call to send event to the application.

Note

lwevt_get_handle() and lwevt_dispatch() are available only when LWEVT_CFG_ENABLE_DEFAULT_HANDLE is enabled

In multi-threading environment, application must ensure thread safety between get handle and dispatch calls. To avoid use of semaphore or mutexes, alternative is to always define local lwevt_t based variable and dispatch event using lwevt_dispatch_ex() function

Produce events with global or local event handle
 1#include "lwevt/lwevt.h"
 2
 3void
 4produce() {
 5    lwevt_t* evt_global;
 6    lwevt_t evt_local;
 7
 8    /*
 9     * Send event using global handle
10     * Thread safety has to be ensured in multi-threading environments
11     */
12    evt_global = lwevt_get_handle();
13    evt_global->msg.ext1.par1 = 10; /* Some value */
14    evt_global->msg.ext1.par2 = 12; /* Some value */
15    lwevt_dispatch(LWEVT_TYPE_MY_EXT_1);
16
17    /*
18     * Send event using local handle
19     * No need to ensure thread safety
20     */
21    evt_local.msg.ext1.par1 = 10;   /* Some value */
22    evt_local.msg.ext1.par2 = 12;   /* Some value */
23    lwevt_dispatch_ex(&evt_local, LWEVT_TYPE_MY_EXT_1);
24    return 0;
25}