Description

Accessing resource objects.

Notes

Resources are always existent virtually (see comment on 'CResource::Get ()'). During their life, they may be registered or unregistered. Local resources are registered by their drivers during the elaboration phase and are typically unregistered when the process terminates. Remote resources are first registered when the connection succeeds and may be temporarily become unregistered if the server connection gets lost.
For an unregistered resource, its owner (driver or host) is not known or set. Its type may be unknown ('rctNone'), its value state is always 'rcsUnknown'. Calling 'Report*' or 'Drive*' methods is not allowed.
For a registered resource, its owner (driver or host) is known and set. Its type is known, and all methods can to be used.
The value type may change (only) during a unregistered -> registered transistion ('Register*' method).
Both requests and subscriptions are preserved when the registration state changes. During unregistration, subscriptions may be "parked" in the subscriber map for efficiency reasons. During registration, requests are converted to the (potentially) new value type. If this fails, a warning is emitted and they are kept with their old type. During evaluations, requests with a type different from its resource are silently ignored.
'Register' and 'Unregister' for one object should always be called from the same thread. The caller is responsible for avoiding concurrent calls of these methods.

The 'timeStamp' attribute points to the time of the last localy known change in state or value.
Only real changes are accounted for. For example, multiple reports of the same value by a driver do not lead to updated time stamps after the first report. In other words, it is known that just before 'timeStamp' the value & state was different from now.
The time stamp is always measured against the local clock. It is ensured that the observed sequence is monotonic, i.e. the age of an event is never smaller than that of the previous event on the same resource.
Network delays are neglected in normal operation, i.e. the time stamp of a remote resource corresponds to the time the respective event was received on the client. (Reasoning: LAN delays are considered very small.) The only exception is when network errors (timeouts) occur (see below).

On reliability and safety-critical operations:

Drivers are responsible to report 'rcsUnknown' themselves immediately within reasonable time if their hardware fails. The maximum delay between the real failure and reporting ("failure report delay") must be stated in the driver documentation.
Network connection failures lead to 'rcsUnknown' on the client immediately, i.e. after a time of at most 'envMaxAge' (default: 60 secs.). On the client, the time stamp is set to max(now - 'envMaxAge', last reported time stamp). This way, the time stamp always points to a time at which the state was not unknown. The time stamp on a client may differ by at most 'envMaxAge' from that on the server. However, both the server and the client observe the time stamp to be monotonous locally.
Safety functions can then be implemented as follows. As an example consider the auto-closing a window on rainy weather, where the window is also to be closed if the rain state is unkown for a time of Tmax. A necessary condition for this to work is that Tmax >= 'envMaxAge'. The rule may be implemented as follows:
- Subscribe to rain sensor, catch all events from now.
- On 'rain == 1': close immediately (normal function)
- On 'rain == rcsUnknown': Safety-close at time t >= rain.timeStamp + Tmax

Collaboration diagram for Resource Objects: