QP/C++ Framework component shall provide the Active Object abstraction to QP/C++ Application
Description
The Active Object abstraction provided by QP/C++ Framework component shall be customizable by QP/C++ Application and executed by QP/C++ according to the Active Object model of computation.
Use Case
QP/C++ Framework component can meet this requirement by providing the Active Object abstraction as a class, which the QP/C++ Applications can customize by subclassing. Such an Active Object base class must be customizable at compile-time for a wide variety of real-time kernels, including traditional blocking RTOS and event-driven, non-blocking kernels.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall be able to manage a compile-time configurable number of Active Objects not exceeding 64 instances.
Description
The maximum number of Active Object instances managed by QP/C++ Framework component at any given time shall be compile-time configurable with a maximum of 64 instances. The actual number of Active Object instances registered with the QP/C++ Framework component at runtime can be lower than the configured compile-time maximum, but it cannot exceed that maximum.
Use Case
For best memory and CPU performance, the maximum number of Active Object instances can be configured below the 64 maximum, and often it might be advantageous to use powers of 2; for example, configure the maximum as 16 or 32 AO instances.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction shall provide the unique priority for each Active Object instance
Description
The Active Object priority is a positive integer number between 1 and the maximum number of Active Objects configured at compile-time (see SRS_QP_AO_01).
Forward Traceability (truncated to 2 level(s))
Active Object priority shall use the direct priority numbering scheme
Description
The Active Object priority shall conform to the direct numbering scheme defined as follows: priority 1 corresponds to the lowest priority, and higher numbers correspond to higher priorities (direct priority numbering scheme). The priority zero cannot be assigned to any Active Object, and is reserved for the idle thread (or the idle condition) of the underlying real-time kernel.
Use Case
The QP priority numbering scheme is fixed and does not change, even if the underlying real-time kernel uses a different priority scheme (e.g., reversed priority numbering). However, the QP priority must remain consistent with the priority of the underlying kernel in that higher QP priority numbers must correspond to a higher (or at least not lower) urgency threads.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction may provide a second "auxiliary priority" for each Active Object instance
Description
The Active Object's "auxiliary priority" may be used for different purposes, depending on the underlying real-time kernel.
Use Cases
In some real-time kernels, the "auxiliary priority" might be used to represent the preemption threshold (e.g., the preemptive QK kernel). In other kernels (e.g., 3rd-party RTOS kernels), it might represent the native thread priority according to the priority numbering scheme of the kernel.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction shall provide an event queue for each Active Object instance
Description
The event queue type shall be compile-time configurable to allow various blocking/non-blocking mechanisms corresponding to the chosen real-time kernel. The capacity of the event queue (maximum number of events it can hold) shall be run-time configurable before the Active Object instance starts executing.
Use Case
QP/C++ Framework component can meet this requirement by providing an event queue as an attribute inside the Active Object class. The type of the event queue must be compile-time configurable to match the underlying real-time kernel that executes the Active Objects in QP.
Forward Traceability (truncated to 2 level(s))
Active Object event queue shall provide FIFO policy for posting events from outside the Active Object
Description
FIFO stands for First-In-First-Out and means that the events are extracted from the queue in the same order in which they have been inserted into the queue.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
Active Object event queue shall additionally provide LIFO policy for self-posting events from within the Active Object
Description
LIFO stands for Last-In-First-Out and means that the events are extracted from the queue in the reversed order in which they have been inserted into the queue. The support for the LIFO policy for self-posting should be in addition to supporting the standard FIFO policy. In other words, the QP/C++ Application can choose to self-post any given event either with the FIFO or LIFO policy.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
The maximum capacity of the Active Object event queue shall be run-time configurable
Description
The maximum capacity of an event queue is the maximum number of events that can be inside the queue at any given time. This maximum capacity shall be determined at run-time.
Use Case
The event queue can be supplied with the buffer memory to hold the events at run-time. The size of that memory buffer will determine the maximum capacity of the event queue.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
Active Object abstraction may provide an optional execution context for each Active Object instance
Description
The execution context (e.g., thread) attribute shall be compile-time configurable to allow various thread types corresponding to the chosen real-time kernel.
Use Case
In case QP uses a traditional RTOS, the execution context might be a thread-control-block (TCB) or just a thread handle/pointer. In the case of other real-time kernels, the execution context might be a thread identifier or might not be needed at all.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component shall allow Active Object instances to be started at runtime
Description
Starting an Active Object instance means registering it with the QP/C++ Framework component, so that the framework can start managing the Active Object. Only after an Active Object instance has been started can it receive and process events. Starting at runtime means that Active Object instances can begin at any time during the regular system operation (as opposed to starting only during system initialization).
Use Case
Starting an Active Object instance might involve initializing its event queue and creating and/or starting the execution context. Only after that, the underlying real-time kernel can include the Active Object in the scheduling process.
Forward Traceability (truncated to 2 level(s))
QP/C++ Framework component may allow Active Object instances to be stopped at runtime
Description
Stopping an Active Object instance means stopping its execution context and unregistering it from the QP/C++ Framework component. Stopping an Active Object does not mean that it is deleted, destroyed, or that its memory is recycled. Stopping only means that the QP/C++ Framework component no longer manages the Active Object and stops participating in scheduling and event processing.
Background
The biggest challenge in stopping an Active Object is to perform it cleanly, without disrupting the rest of the application. For example, the stopped Active Object should not receive any events from the rest of the application. Also, the Active Object should not have any events to process in its queue. For these reasons, stopping an Active Object is optional, and is not recommended, especially in safety-related applications. Instead of stopping an Active Object, a better design is to post a special event to that Active Object, which could trigger a transition to a special "stopped" state in the Active Object's state machine.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction may provide an optional "operating-system object" for each Active Object instance
Description
The optional "operating system object" shall be compile-time configurable to allow various operating-system object types corresponding to the selected real-time kernel.
Use Case
For example, the Active Object's event-queue for the POSIX operating system might require an additional condition-variable attribute ("operating system object") to implement blocking on an empty queue.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction shall encapsulate its internals
Description
The Active Object abstraction should hide and protect its internals, both for reading and writing by any outside entities. Additionally, the QP/C++ Framework component shall allow the QP/C++ Application to hide and protect any additional attributes added to the derived Active Objects.
Forward Traceability (truncated to 2 level(s))
Active Object abstraction shall allow Applications to access the internal attributes from inside the Active Object easily
Description
Notwithstanding Requirement SRS_QP_AO_10, the QP/C++ Framework component shall allow for easy and computationally inexpensive access to the internal attributes of an Active Object from within the AO, such as from its internal state machine.
Use Case
A good example of implementing such a policy is the concept of class encapsulation in OOP, where the internal attributes are accessible to the class operations (e.g., via the this pointer) and are harder to access from the outside.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
Active Object abstraction shall support run-to-completion event processing
Description
QP/C++ Framework component must guarantee that every event is processed to completion, regardless of the real-time kernel used, and that during the RTC step, the current event remains available and unchanged.
Active Object abstraction shall provide support for state machines.
Description
Each Active Object instance shall have an internal state machine, with the features and semantics specified in Section State Machines. QP/C++ Framework component shall guarantee execution of such internal state machines in a Run-to-Completion fashion.
Backward Traceability
Forward Traceability (truncated to 2 level(s))
