QP/C++
8.0.0
Real-Time Embedded Framework
One of the main responsibilities of the QP/C++ Framework is to reliably and safely deliver QP events from various producers to Active Objects. The event delivery is asynchronous, meaning that the producers only post events to Active Objects, but don't wait in-line for the processing of the events. Any part of the system can produce events, not necessarily only the Active Objects. For example, ISRs, device drivers, or legacy code running outside the framework can produce events. On the other hand, only Active Objects can consume QP/C++ events, because only Active Objects are guaranteed to have event queues.
Event delivery mechanisms can be broadly classified into the following two categories (see Figure SRS-EDM):
Direct event posting is the simplest mechanism that allows producers to post events directly to the event queue of the recipient Active Object. Figure SRS-EDM illustrates this form of communication as red arrows directly connecting event producers and the consumer Active Objects.
Direct event posting is a "push-style" communication mechanism, in which recipients receive unsolicited events whether they "want" them or not. Direct event posting is well suited for situations where a group of Active Objects, or an Active Object and an ISR, form a subsystem providing a particular service, such as a communication stack, GPS capability, digital camera subsystem in a mobile phone, or the like. This style of event passing requires that the event producers "knows" the recipients and their interests in various events. The "knowledge" that a sender needs is, at a minimum, the handle (e.g., a pointer) to the recipient Active Object.
Direct event posting mechanism might increase the coupling among the components, especially when the recipients of the events are hard-coded inside the event producers. However, one way of reducing the coupling is to allow the recipients to "register" with the producers at runtime (e.g., event producer can store a pointer to the direct consumer of the events). That way the producer does not need to hard-code the recipient(s).
Publish-subscribe event delivery is shown in Figure SRS-EDM as a "software bus" into which Active Objects "plug in" through the specified interface. Active Objects interested in certain events subscribe to one or more event signals by the QP/C++ Framework. When an event producer chooses to publish an event, QP/C++ Framework delivers the event to all subscribers, which entails event multicasting the event (sometimes incorrectly called broadcasting). Publication requests can originate asynchronously from many sources, not necessarily just from Active Objects. For example, events can be published from interrupts (ISRs), device drivers, or the "naked" threads (in case QP/C++ runs on top of a conventional RTOS/OS).
Publish-subscribe is a "pull-style" communication mechanism in which recipients receive only solicited (subscribed) events. The properties of the publish-subscribe model are:
| SRS_QP_EDM_00 : QP/C++ Framework shall provide direct event posting to Active Object instances based on the FIFO policy |
|---|
| Description The direct event posting mechanism shall post events to the event queue of the recipient Active Object utilizing the FIFO (First-In-First-Out) policy. Direct event posting with the default FIFO policy shall be available to all possible event producers, such as Active Objects, but also interrupts (ISRs), "device drivers", and "naked" threads of an RTOS (if an RTOS is used to run QP). |
Backward Traceability
|
Forward Traceability
|
| SRS_QP_EDM_01 : QP/C++ Framework shall provide direct event self-posting to Active Object instances based on the LIFO policy |
|---|
| Description Self-posting means that a given Active Object instance posts event to its own event queue. Such self-posting mechanism shall use the same event queue as the default FIFO policy, but in addition to the default FIFO policy it should provide also the LIFO (Last-In-First-Out) policy. This self-posting with the LIFO policy shall use a distinctly different API than the default direct event posting with the FIFO policy. |
| Use case Self-posting of events with the LIFO policy can be useful for recalling events that have been deferred by the Active Object instance. |
Backward Traceability
|
Forward Traceability
|
| SRS_QP_EDM_50 : QP/C++ Framework shall provide publish-subscribe event delivery mechanism |
|---|
| Description Publish-subscribe shall use direct event posting (default, reliable variant based on FIFO policy) as the underlying low-level mechanism to multicast the subscribed events. |
Forward Traceability
|
| SRS_QP_EDM_51 : The publish-subscribe event delivery mechanism shall be configurable and optional |
|---|
| Description The QP/C++ Application shall initialize and configure the publish-subscribe delivery mechanism by supplying the maximum number of event signals that can be subscribed and a memory buffer to store the subscription information. As a special case, QP/C++ Application might choose not to initialize publish-subscribe, in which case the feature shall be inactive and shall not cause any waste of resources (RAM). |
Backward Traceability
|
| Use case QP/C++ Application initializes the publish-subscribe event delivery for a given maximum number of event signals and provides memory buffer capable of holding that many signals for the maximum allowed number of Active Objects in QP/C++ Application (see SRS_QP_AO_01). |
Forward Traceability
|
| SRS_QP_EDM_52 : QP/C++ Framework shall allow Active Object instances to subscribe to a given event signal at run-time. |
|---|
| Description QP/C++ Framework shall provide API for Active Objects to subscribe one event signal at a time. The API shall be callable multiple times by a given Active Object to subscribe to multiple event signals. Event subscription requires initialization of the publish-subscribe feature and attempts to subscribe without prior initialization shall be treated as a programming error. Similarly, subscribing to an already subscribed signal (by the same Active Object) shall be treated as a programming error. |
Backward Traceability
|
Forward Traceability
|
| SRS_QP_EDM_53 : QP/C++ Framework shall allow Active Object instances to unsubscribe from a subscribed event signal at run-time. |
|---|
| Description QP/C++ Framework shall provide API for Active Objects to unsubscribe one event signal at a time. The API shall be callable multiple times by a given Active Object to unsubscribe from multiple event signals. Event un-subscription requires initialization of the publish-subscribe feature and attempts to unsubscribe without prior initialization shall be treated as a programming error. Similarly, unsubscribing from a signal that has not been subscribed shall be treated as a programming error. |
Backward Traceability
|
Forward Traceability
|
| SRS_QP_EDM_54 : QP/C++ Framework shall allow Active Object instances to unsubscribe from all subscribed event signals at run-time. |
|---|
| Description QP/C++ Framework shall provide API for Active Objects to unsubscribe from all event signals at ones. Event un-subscription requires initialization of the publish-subscribe feature and attempts to unsubscribe without prior initialization shall be treated as a programming error. |
Forward Traceability
|
| SRS_QP_EDM_55 : Event multicasting during publishing shall complete before the processing of the published events. |
|---|
| Description The purpose of this requirement is to prevent event publishing from creating unexpected event sequences when QP/C++ Framework runs on top of a preemptive kernel. As specified in SRS_QP_EDM_50, event multicasting (required when a given event signal is subscribed by multiple Active Objects) uses the default direct event posting mechanism. However, if the priority of the event producer is lower than the priority of the recipient Active Object, direct event posting would normally lead to preemption (before multicasting completes). Such a preemption would then cause the high-priority Active Object to immediately process the published event, which might produce other events. These other events would then appear in the event queues of Active Objects before the originally published event. This would generate a confusing event sequence. |
Backward Traceability
|
| Use Case QP/C++ Framework can fulfill this requirement by preventing preemption during the event multicasting (only needed when QP/C++ Framework runs on top of a preemptive kernel). The preemption should be prevented only for the priorities of Active Objects involved in this particular multicasting. An ideal mechanism for that is selective scheduler locking based on priority ceiling protocol. The priority ceiling shall be set to the highest priority subscriber to a given event. |
| Forward Traceability |
| SRS_QP_EDM_80 : All event delivery mechanisms shall be free of concurrency hazards. |
|---|
| Description "Free of concurrency hazards" means free of such hazards as as race conditions and data races. It also means that QP/C++ Framework must ensure that the current event does not change (e.g., is not corrupted or prematurely recycled) throughout all RTC steps it is involved in. |
| Forward Traceability |
| SRS_QP_EDM_81 : All event delivery mechanism shall be deterministic. |
|---|
| Description "Deterministic" means that the process of event posting or publishing has a known and constant upper bound of its execution time. In case of event publishing, QP/C++ Framework cannot meet this requirement alone because the time of event multicasting depends on the number of subscribers to a given event, so it is not constant. Therefore, QP/C++ Application must be designed in such a way that the multicasting time is acceptable. |
| Forward Traceability |