RTC::LightweightRTObject Interface Reference
import "RTC.idl";
Detailed Description
Description
This interface is realized by all lightweight RTCs (as required by the lightweightRTComponent stereotype). It defines the states and transitions through which all RTCs will pass from the time they are created until the time they are destroyed.
Semantics
Initialization
An RTC begins in the Created state; at this point, it has been instantiated but not yet fully initialized. Note that this state is highly implementation-dependent. For example, it may correspond to the invocation of a constructor in languages that support that concept, but not all languages do. Furthermore, how soon this state is entered before initialize is invoked is implementation-dependent. Therefore, it should be relied on by RTC implementers only to the minimum extent possible. An RTC that has completed its initialization and has not been finalized is said to be Alive.
Context
An RTC in the Alive state may participate in any number of execution contexts (see Section 5.2.2.5 ). These contexts shall be represented to an RTC as distinct instances of the ExecutionContext class. The ExecutionContext manages the behavior of each RTC that participates in it. This relationship is defined by the following state machine, which is embedded within the ExecutionContext's own lifecycle (see Figure 5.5 ). Each participating RTC is represented as a separate parallel region.
Relative to a given execution context, an RTC may either be Active, Inactive, or in Error. When the RTC is Active in a Running execution context, the ComponentAction callbacks (see Section 5.2.2.4) shall be invoked as appropriate for the context¡Ç s ExecutionKind. The callbacks shall not be invoked relative to that context when either the RTC is Inactive in that context or the context is Stopped. (Note that starting and stopping an execution context shall not impact whether its participating RTCs are Active or Inactive.) It may be that a given RTC does not directly participate in any execution contexts. Such an RTC is referred to as passive. A passive RTC may provide services to other components upon request. At any other time, it shall not be required to perform any ongoing activity of its own; therefore, instances of such an RTC typically exist only as parts (directly or indirectly) of a containing active RTC.
Handling
If an operation fails while the RTC is Active in a given execution context, the RTC will transition to the Error state corresponding to that context. While the RTC is in Error, the ComponentAction::on_error callback will be invoked in place of those callbacks that would otherwise have been invoked according to the context¡Çs ExecutionKind. For example, if the kind is PERIODIC, on_error shall be invoked instead of the pair of on_execute, and on_state_update. When an RTC is in Error, it may be reset. If resetting is successful, the RTC shall return to the Inactive state. If resetting is unsuccessful, it shall remain in the Error state.
Member Function Documentation
| ExecutionContextHandle_t RTC::LightweightRTObject::attach_context | ( | in ExecutionContext | exec_context | ) |
attach_context
Description
Inform this RTC that it is participating in the given execution context. Return a handle that represents the association of this RTC with the context.
Semantics
This operation is intended to be invoked by ExecutionContextOperations::add_component (see Section 5.2.2.6.6). It is not intended for use by other clients.
| ReturnCode_t RTC::LightweightRTObject::detach_context | ( | in ExecutionContextHandle_t | exec_handle | ) |
detach_context
Description
Inform this RTC that it is no longer participating in the given execution context.
Semantics
This operation is intended to be invoked by ExecutionContextOperations::remove_component (see Section 5.2.2.6.7). It is not intended for use by other clients.
Constraints
- This operation may not be invoked if this RTC is not already participating in the execution context. Such a call shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
- This operation may not be invoked if this RTC is Active in the indicated execution context. Otherwise, it shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
| ReturnCode_t RTC::LightweightRTObject::exit | ( | ) |
exit
Description
Stop the RTC¡Çs execution context(s) and finalize it along with its contents.
Semantics
Any execution contexts for which the RTC is the owner shall be stopped. If the RTC participates in any execution contexts belonging to another RTC that contains it, directly or indirectly (i.e., the containing RTC is the owner of the ExecutionContext), it shall be deactivated in those contexts. After the RTC is no longer Active in any Running execution context, it and any RTCs contained transitively within it shall be finalized.
Constraints
An RTC cannot be exited if it has not yet been initialized. Any attempt to exit an RTC that is in the Created state shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
| ReturnCode_t RTC::LightweightRTObject::finalize | ( | ) |
finalize
Description
Finalize the RTC that realizes this interface, preparing it for destruction.
Semantics
This invocation of this operation shall result in the invocation of the callback ComponentAction::on_finalize
Constraints
- An RTC may not be finalized while it is participating in any execution context. It must first be removed with ExecutionContextOperations::remove_component. Otherwise, this operation shall fail with ReturnCode_t::PRECONDITION_NOT_MET. See Figure 5.9.
- An RTC may not be finalized while it is in the Created state. Any attempt to invoke this operation while in that state shall fail with ReturnCode_t::PRECONDITION_NOT_MET.
- Application developers are not expected to call this operation directly; it exists for use by the RTC infrastructure.
| ExecutionContext RTC::LightweightRTObject::get_context | ( | in ExecutionContextHandle_t | exec_handle | ) |
get_context
Description
Obtain a reference to the execution context represented by the given handle.
Semantics
The mapping from handle to context is specific to a particular RTC instance. The given handle must have been obtained by a previous call to attach_context on this RTC.
| ExecutionContextHandle_t RTC::LightweightRTObject::get_context_handle | ( | in ExecutionContext | cxt | ) |
get_context_handle
Description
This operation returns a handle that is associated with the given execution context.
| ExecutionContextList RTC::LightweightRTObject::get_owned_contexts | ( | ) |
get_owned_contexts
Description
This operation returns a list of all execution contexts owned by this RTC.
| ExecutionContextList RTC::LightweightRTObject::get_participating_contexts | ( | ) |
* get_participating_contexts
Description
This operation returns a list of all execution contexts in which this RTC participates.
Semantics
Each call to attach_context causes the provided context to be added to this list. Each call to detach_context causes the provided context to be removed from this list.
| ReturnCode_t RTC::LightweightRTObject::initialize | ( | ) |
initialize
Description
Initialize the RTC that realizes this interface.
Semantics
The invocation of this operation shall result in the invocation of the callback ComponentAction::on_initialize.
Constraints
| boolean RTC::LightweightRTObject::is_alive | ( | in ExecutionContext | exec_context | ) |
is_alive
Description
A component is alive or not regardless of the execution context from which it is observed. However, whether or not it is Active, Inactive, or in Error is dependent on the execution context(s) (see Figure 5.7) in which it is running. That is, it may be Active in one context but Inactive in another. Therefore, this operation shall report whether this RTC is either Active, Inactive, or in Error; which of those states a component is in with respect to a particular context may be queried from the context itself.
| ReturnCode_t RTC::ComponentAction::on_aborting | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
on_aborting
Description
The RTC is transitioning from the Active state to the Error state in some execution context.
Semantics
This callback is invoked only a single time for time that the RTC transitions into the Error state from another state. This behavior is in contrast to that of on_error.
| ReturnCode_t RTC::ComponentAction::on_activated | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
| ReturnCode_t RTC::ComponentAction::on_deactivated | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
| ReturnCode_t RTC::ComponentAction::on_error | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
on_error
Description
The RTC remains in the Error state.
Semantics
If the RTC is in the Error state relative to some execution context when it would otherwise be invoked from that context (according to the context¡Çs ExecutionKind), this callback shall be invoked instead. For example,
- If the ExecutionKind is PERIODIC, this operation shall be invoked in sorted order at the rate of the context instead of DataFlowComponentAction::on_execute and on_state_update.
- If the ExecutionKind is EVENT_DRIVEN, this operation shall be invoked whenever FsmParticipantAction::on_action would otherwise have been invoked.
| ReturnCode_t RTC::ComponentAction::on_finalize | ( | ) | [inherited] |
on_finalize
Description
The RTC is being destroyed.
Semantics
Any final RTC-specific tear-down logic should be performed here.
| ReturnCode_t RTC::ComponentAction::on_initialize | ( | ) | [inherited] |
on_initialize
Description
The RTC has been initialized and entered the Alive state.
Semantics
Any RTC-specific initialization logic should be performed here.
| ReturnCode_t RTC::ComponentAction::on_reset | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
on_reset
Description
The RTC is in the Error state. An attempt is being made to recover it such that it can return to the Inactive state.
Semantics
If the RTC was successfully recovered and can safely return to the Inactive state, this method shall complete with ReturnCode_t::OK. Any other result shall indicate that the RTC should remain in the Error state.
| ReturnCode_t RTC::ComponentAction::on_shutdown | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
on_shutdown
Description
The given execution context, in which the RTC is participating, has transitioned from Running to Stopped.
| ReturnCode_t RTC::ComponentAction::on_startup | ( | in ExecutionContextHandle_t | exec_handle | ) | [inherited] |
on_startup
Description
The given execution context, in which the RTC is participating, has transitioned from Stopped to Running.
The documentation for this interface was generated from the following file:
