Events

Events are messages that can be queued from almost any place in your application and handled by message handlers.

Each event has message type and payload. Although internally message type is unsigned char*, it shall not be treated as a string, because it is compared for the precise equivalence of the pointer, not content. Payload is void* and event type dependent including a possibility to use NULL pointer if payload is not required.

Loviisa uses several standard event types, however normally user shall introduce new event type for his needs.

To declare a new event type user shall put the following declaration into the global context of any C file outside of function definitions:

• LVS_DEFINE_EVENT_TYPE(type_name) where type_name is any unique identifier. If the event type is used outside of this C file, it shall be declared as:
• LVS_USE_EVENT_TYPE(type_name) To get event type initialized, the following initialization routine shall be called in the initialization routine or main() function:
• LVS_CREATE_EVENT_TYPE(type_name)

Event type will be available for sending and subscribing on if properly defined and created.

Event subscriber is any function with following specification:

• LVS_ERROR_T func(LVS_EVENT_T);

Each event type may have multiple subscribers. To define a function as a potential subscriber (to any event type) use:

• LVS_DEFINE_SUBSCRIBER(func) in a global context of C file. If you need to reuse the subscription, put:
• LVS_USE_SUBSCRIBER(func) in any other C or H file. To inform the system that the subscriber function has to be called upon the given type of events use:
• LVS_ADD_SUBSCRIBER(type_name, func) The same function can be used as a subscriber for multiple event types although it is not recommended, but has no restrictions.

If you are capable to use only short reactions on events without any long consequent algorithms, using of events and subscriptions only is a best method to obtain fast and responsive software without locks and delays. It is a recommended programming method for control systems development without complicated calculations and long executing loops. If such loops are unavoidable, task-based technique shall be combined with events handling.

LVS_RESEND(event) sends event back to the queue from the event handler. Just for the case when event handler cannot process the event immediately (for example because of timings or conditions)

LVS_BEGIN_CRITICAL_SECTION() - locks event scheduler

LVS_END_CRITICAL_SECTION() - unlocks event scheduler

Critical sections must be used with a lot of care and normally not required if timings of all tasks and events are adjusted properly.