.. _um:

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