index.rst

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 :ref:`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:

• Basic event type with :c:macro:`LWEVT_TYPE_BASIC`
• Extended event type with :c:macro:`LWEVT_TYPE_EXT` that also includes data structure to be part of event

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.

.. literalinclude:: ../../examples/lwevt_types.h
    :language: c
    :linenos:
    :caption: Definition of event types

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.

.. literalinclude:: ../../examples/example_basic_producer.c
    :language: c
    :linenos:
    :caption: Produce event to all subscribers

Subscribe to events

Subscribing to events involves calling :cpp:func:`lwevt_register` function with callback function as parameter. All events are processed in the callback function from now on.

.. literalinclude:: ../../examples/example_basic_consumer.c
    :language: c
    :linenos:
    :caption: Receive events from the application

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 :cpp:func:`lwevt_get_handle` function and allows use of default :cpp:func:`lwevt_dispatch` function call to send event to the application.

Note

:cpp:func:`lwevt_get_handle` and :cpp:func:`lwevt_dispatch` are available only when :c:macro:`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 :cpp:type:`lwevt_t` based variable and dispatch event using :cpp:func:`lwevt_dispatch_ex` function

.. literalinclude:: ../../examples/example_basic_producer_local.c
    :language: c
    :linenos:
    :caption: Produce events with global or local event handle

.. toctree::
    :maxdepth: 2