QP/C++ Framework component 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 (truncated to 2 level(s))
QP/C++ Framework component 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 an event to its event queue. Such a self-posting mechanism shall use the same event queue as the default FIFO policy. Still, in addition to the default FIFO policy, it should also provide 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 the Active Object instance has deferred.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall provide event delivery guarantee for the direct event posting mechanism.
Description
The event delivery guarantee shall be implemented with the SSFs based on assertion programming specified in SSRS_QP_FDM_00. QP/C++ Framework component shall detect all conditions that could prevent a posted event from reaching the recipient Active Object (in particular, event queue overflow and event-pool depletion for mutable events). In case any such condition occurs, QP/C++ Framework component shall relinquish control and invoke the custom error handler defined in QP/C++ Application (see SSRS_QP_FDM_20). That way, QP/C++ Application does not need to check whether direct event posting was successful (because continuing execution means that it was).
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component 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 (truncated to 2 level(s))
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 to 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. It provides a memory buffer capable of holding that many signals for the maximum allowed number of Active Objects in the QP/C++ Application (see SRS_QP_AO_01).
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall allow Active Object instances to subscribe to a given event signal at run-time.
Description
QP/C++ Framework component shall provide an API for Active Objects to subscribe to one event signal at a time. The API shall be callable multiple times by a given Active Object to subscribe to various 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 (truncated to 2 level(s))
QP/C++ Framework component shall allow Active Object instances to unsubscribe from a subscribed event signal at run-time.
Description
QP/C++ Framework component 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 various 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 to shall be treated as a programming error.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall allow Active Object instances to unsubscribe from all subscribed event signals at run-time.
Description
QP/C++ Framework component shall provide an API for Active Objects to unsubscribe from all event signals at once. 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 (truncated to 2 level(s))
Event multicasting during publishing shall be completed before the processing of the published events.
Description
The purpose of this requirement is to prevent event publishing from creating unexpected event sequences when the QP/C++ Framework component runs on top of a preemptive kernel. As specified in SRS_QP_EDM_50, event multicasting (required when multiple Active Objects subscribe to a given event signal) 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 typically 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 different events would then appear in the event queues of Active Objects before the published initially event. This would generate a confusing event sequence.
Backward Traceability
Use Case
QP/C++ Framework component can fulfill this requirement by preventing preemption during the event multicasting (only needed when QP/C++ Framework component 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 the priority ceiling protocol. The priority ceiling shall be set to the highest priority subscriber to a given event.
Forward Traceability (truncated to 2 level(s))
QP/C++ Application shall adequately size all event queues and event pools.
Description
According to the QP/C++ Framework component memory allocation policy defined in the Software Architecture Specification, the size of event queues and event pools is determined by QP/C++ Application, not by QP/C++ Framework component. Therefore, to achieve event delivery guarantee required in SRS_QP_EDG-10, the QP/C++ Application must supply adequate sizes for the event queues and event pools.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component may provide alternative best-effort event posting mechanism without event delivery guarantee
Description
The alternative best-effort event posting mechanism without event delivery guarantee shall detect that a given event cannot be posted, but QP/C++ Framework component should pass this information to QP/C++ Application instead of entering a fail-safe state. The alternative direct event posting mechanism without event delivery guarantee must use a different API than the default mechanism with delivery guarantee.
Use Case
Event posting without event delivery guarantee is useful for events that the application can afford to lose occasionally and can apply only best effort to handle.
Forward Traceability (truncated to 2 level(s))
The alternative unreliable event posting mechanism shall not interfere with the default reliable event posting
Description
An example of interference between the two event posting mechanisms is exhausting the queue capacity by the unreliable event posting, so that the reliable event posting fails. Consequently, the unreliable event posting mechanism should not exhaust the event queue resource completely, but rather leave a specified number of unused queue entries (a safety margin) for the reliable event delivery.
Use Case
When using the unreliable direct event posting mechanism, the QP/C++ Application shall specify a non-zero safety margin of the event queue to which it posts events that can be lost. The unreliable posting should fail (and convey this failure to the QP/C++ Application) when the safety margin is reached. That way, some space in the queue remains available to the reliable (default) event posting mechanism.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
Mutable event allocation shall be reliable. This requirement also means that the QP/C++ Application is responsible for adequately sizing all event pools.
Description
"Reliable" event allocation means that the QP/C++ Framework component shall detect if the mutable event cannot be allocated (e.g., due to depletion of an event pool of a given block size). In case allocation fails, the QP/C++ Framework component shall enter a fail-safe state. This reliable event allocation policy shall be the default.
Use Case
The default (reliable) event allocation policy frees the QP/C++ Application from checking whether event allocation was successful (because continuing execution means that it was).
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component may provide alternative unreliable method of allocating mutable events.
Description
The alternative, best-effort only method of allocating mutable events must use a different API than the default reliable event allocation. QP/C++ Framework component still shall detect that a mutable event cannot be allocated, but the framework should pass this information to the QP/C++ Application instead of entering a fail-safe state. The unreliable event allocation policy shall be a special case and should be used with caution.
Use Case
Unreliable event allocation is useful for events that the application can afford to lose occasionally and can apply only "best effort" to allocate and deliver.
Forward Traceability (truncated to 2 level(s))
The alternative best-effort event allocation method shall not interfere with the default reliable event allocation.
Description
The alternative unreliable event allocation must co-exist with the default reliable event allocation. An example of interference between the two event allocation methods is exhausting queue capacity by the unreliable event posting, so that the reliable event posting fails and causes the system to enter a fail-safe state.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
All event delivery mechanisms shall be free of concurrency hazards.
Description
"Free of concurrency hazards" means free of such hazards as race conditions and data races. It also means that the QP/C++ Framework component 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 (truncated to 2 level(s))
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 on its execution time. In the case of event publishing, the QP/C++ Framework component 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, the QP/C++ Application must be designed in such a way that the multicasting time is acceptable.
Forward Traceability (truncated to 2 level(s))
