RTC::ExecutionContext Interface Reference
import "RTC.idl";
Public Member Functions | |
| boolean | is_running () |
| is_running | |
| ReturnCode_t | start () |
| start | |
| ReturnCode_t | stop () |
| stop | |
| double | get_rate () |
| get_rate | |
| ReturnCode_t | set_rate (in double rate) |
| set_rate | |
| ReturnCode_t | add_component (in LightweightRTObject comp) |
| add_component | |
| ReturnCode_t | remove_component (in LightweightRTObject comp) |
| remove_component | |
| ReturnCode_t | activate_component (in LightweightRTObject comp) |
| activate_component | |
| ReturnCode_t | deactivate_component (in LightweightRTObject comp) |
| deactivate_component | |
| ReturnCode_t | reset_component (in LightweightRTObject comp) |
| reset_component | |
| LifeCycleState | get_component_state (in LightweightRTObject comp) |
| get_component_state | |
| ExecutionKind | get_kind () |
| get_kind | |
Detailed Description
Description
An ExecutionContext allows the business logic of an RTC to be decoupled from the thread of control in which it is executed. The context represents a logical thread of control and is provided to RTCs at runtime as an argument to various operations, allowing them to query and modify their own state, and that of other RTCs executing within the same context, in the lifecycle. This separation of concerns is important for two primary reasons:
- Large number of components may collaborate tightly within a single node or process. If each component were to run within its own thread of control, the infrastructure may not be able to satisfy the timeliness and determinism requirements of real-time applications due to the large number of threads and the required synchronization between them.
- A single application may carry out a number of independent tasks that require different execution rates. For example, it may need to sample a sensor periodically at a very high rate and update a user interface at a much lower rate.
Semantics
The state machine of an ExecutionContext has two parts. The behavior of the ExecutionContext itself is defined by the upper region in the above figure. The behavior of the RTCs that participate in the context is defined by the lower region. The contents of that region are displayed in more detail in Figure 5.5 in Section 5.2.2.2. Ownership and Participation Each execution context is owned by a single RTC and may be used to execute that RTC and the RTCs contained within it, directly or indirectly. An RTC that owns one or more execution contexts is known as an autonomous RTC. An autonomous RTC and some subset of the RTCs within it (to be defined by the application developer) shall be executed by the infrastructure according to the context¡Ç s execution kind, which defines when each RTC¡Çs operations will be invoked when and in which order. These RTCs are said to participate in the context. The available execution kinds are described in Section 5.2.2.7. The relationship between RTCs and execution contexts may be many-to-many in the general case: multiple RTCs may be invoked from the same execution context, and a single RTC may be invoked from multiple contexts. In the case where multiple RTCs are invoked from the same context, starting or stopping the context shall result in the corresponding lifecycle transitions for all of those components.
and Physical Threads
Although an execution context represents a logical thread of control, the choice of how it maps to a physical thread shall be left to the application¡Çs deployment environment. Implementations may elect to associate contexts with threads with a one-to-one mapping, to serve multiple contexts from a single thread, or by any other means. In the case where a given RTC may be invoked from multiple contexts, concurrency management is implementation-dependent.
Member Function Documentation
| ReturnCode_t RTC::ExecutionContext::activate_component | ( | in LightweightRTObject | comp | ) |
activate_component
Description
The given participant RTC is Inactive and is therefore not being invoked according to the execution context¡Çs execution kind. This operation shall cause the RTC to transition to the Active state such that it may subsequently be invoked in this execution context.
Semantics
The callback on_activate shall be called as a result of calling this operation. This operation shall not return until the callback has returned, and shall result in an error if the callback does. The following figure is a non-normative example sequence diagram for activate_component.
Constraints
- An execution context can only activate its participant components. If the given RTC is not participating in the execution context, this operation shall fail with ReturnCode_t::BAD_PARAMETER.
- An RTC that is in the Error state cannot be activated until after it has been reset. If the given RTC is in the Error state, this operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
- This operation shall fail with ReturnCode_t::BAD_PARAMETER if the given component is not in its Alive state.
| ReturnCode_t RTC::ExecutionContext::add_component | ( | in LightweightRTObject | comp | ) |
add_component
Description
The operation causes the given RTC to begin participating in the execution context.
Semantics
The newly added RTC will receive a call to LightweightRTComponent::attach_context (see Section 5.2.2.2.5) and then enter the Inactive state.
Constraints
- If the ExecutionKind of this context is PERIODIC, the RTC must be a data flow component (see Section 5.3.1.1). Otherwise, this operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
- If the ExecutionKind of this context is EVENT_DRIVEN, the RTC must be an FSM participant (see Section 5.3.2.3). Otherwise, this operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
| ReturnCode_t RTC::ExecutionContext::deactivate_component | ( | in LightweightRTObject | comp | ) |
deactivate_component
Description
The given RTC is Active in the execution context. Cause it to transition to the Inactive state such that it will not be subsequently invoked from the context unless and until it is activated again.
Semantics
The callback on_deactivate shall be called as a result of calling this operation. This operation shall not return until the callback has returned, and shall result in an error if the callback does. The following figure is a non-normative example sequence diagram for deactivate_component.
Constraints
- An execution context can only deactivate its participant components. If the given RTC is not participating in the execution context, this operation shall fail with ReturnCode_t::BAD_PARAMETER.
- This operation shall fail with ReturnCode_t::BAD_PARAMETER if the given component is not in its Alive state.
| LifeCycleState RTC::ExecutionContext::get_component_state | ( | in LightweightRTObject | comp | ) |
get_component_state
Description
This operation shall report the LifeCycleState of the given participant RTC.
Constraints
- The given RTC must be Alive.
- The given RTC must be a participant in the target execution context.
- The LifeCycleState returned by this operation shall be one of LifeCycleState::INACTIVE, ACTIVE, or ERROR.
| ExecutionKind RTC::ExecutionContext::get_kind | ( | ) |
| double RTC::ExecutionContext::get_rate | ( | ) |
get_rate
Description
This operation shall return the rate (in hertz) at which its Active participating RTCs are being invoked.
Semantics
An implementation is permitted to perform some periodic or quasi-periodic processing within an execution context with an ExecutionKind other than PERIODIC. In such a case, the result of this operation is implementation-defined. If no periodic processing of any kind is taking place within the context, this operation shall fail as described in Section 5.2.1.
Constraints
- If the context has an ExecutionKind of PERIODIC, this operation shall return a rate greater than zero.
| boolean RTC::ExecutionContext::is_running | ( | ) |
is_running
Description
This operation shall return true if the context is in the Running state.
Semantics
While the context is Running, all Active RTCs participating in the context shall be executed according to the context¡Çs execution kind.
| ReturnCode_t RTC::ExecutionContext::remove_component | ( | in LightweightRTObject | comp | ) |
remove_component
Description
This operation causes a participant RTC to stop participating in the execution context.
Semantics
The removed RTC will receive a call to LightweightRTComponent::detach_context (see Section 5.2.2.2.6).
Constraints
- If the given RTC is not currently participating in the execution context, this operation shall fail with ReturnCode_t::BAD_PARAMETER.
| ReturnCode_t RTC::ExecutionContext::reset_component | ( | in LightweightRTObject | comp | ) |
reset_component
Description
Attempt to recover the RTC when it is in Error.
Semantics
The ComponentAction::on_reset callback shall be invoked. This operation shall not return until the callback has returned, and shall result in an error if the callback does. If possible, the RTC developer should implement that callback such that the RTC may be returned to a valid state. * If this operation fails, the RTC will remain in Error.
Constraints
| ReturnCode_t RTC::ExecutionContext::set_rate | ( | in double | rate | ) |
set_rate
Description
This operation shall set the rate (in hertz) at which this context¡Çs Active participating RTCs are being called.
Semantics
If the execution kind of the context is PERIODIC, a rate change shall result in the invocation of on_rate_changed on any RTCs realizing DataFlowComponentAction that are registered with any RTCs participating in the context. An implementation is permitted to perform some periodic or quasi-periodic processing within an execution context with an ExecutionKind other than PERIODIC. If such is the case, and the implementation reports a rate from get_rate, this operation shall set that rate successfully provided that the given rate is valid. If no periodic processing of any kind is taking place within the context, this operation shall fail with ReturnCode_t::UNSUPPORTED.
Constraints
- The given rate must be greater than zero. Otherwise, this operation shall fail with ReturnCode_t::BAD_PARAMETER.
| ReturnCode_t RTC::ExecutionContext::start | ( | ) |
start
Description
Request that the context enter the Running state. Once the state transition occurs, the ComponentAction::on_startup operation (see Section 5.2.2.4.3) will be invoked.
Description
Semantics
An execution context may not be started until the RT components that participate in it have been initialized. An execution context may be started and stopped multiple times.
Constraints
- This operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET if the context is not in the Stopped state.
- This operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET if any of the participating components are not in their Alive state.
| ReturnCode_t RTC::ExecutionContext::stop | ( | ) |
stop
Description
Request that the context enter the Stopped state. Once the transition occurs, the ComponentAction::on_shutdown operation (see Section 5.2.2.4.4) will be invoked.
Semantics
An execution context must be stopped before the RT components that participate in it are finalized.
An execution context may be started and stopped multiple times.
Constraints
- This operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET if the context is not in the Running state.
The documentation for this interface was generated from the following file:
