Oberon || Library || Module Index || Search Engine || Definition || Module

Ulm's Oberon Library:
Resources

NAME

SYNOPSIS

TYPE Resource = Disciplines.Object;



CONST terminated = 0;
CONST unreferenced = 1;
CONST communicationStopped = 2;
CONST communicationResumed = 3;
TYPE StateChange = SHORTINT; (* terminated..communicationResumed *)



TYPE Event = POINTER TO EventRec; (* notification of state changes *)
TYPE EventRec =
   RECORD
      (Events.EventRec)
      change: StateChange;
      resource: Resource;
   END;



TYPE Key = POINTER TO KeyRec;
TYPE KeyRec = RECORD (Objects.ObjectRec) END;



PROCEDURE TakeInterest(resource: Resource; VAR eventType: Events.EventType);
PROCEDURE Notify(resource: Resource; change: StateChange);
PROCEDURE DependsOn(dependant, resource: Resource);
PROCEDURE Attach(resource: Resource; VAR key: Key);
PROCEDURE Detach(resource: Resource; key: Key);
PROCEDURE Alive(resource: Resource) : BOOLEAN;
PROCEDURE Stopped(resource: Resource) : BOOLEAN;
PROCEDURE Terminated(resource: Resource) : BOOLEAN;

DESCRIPTION

• no termination handler gets invoked when the object is collected and
• the object wouldn't be collected at all if it is member of bookkeeping data structures which would like to get rid of otherwise unused objects (light-weighted references).

Objects which follow through on Resources are in one of five states:

alive

This is the initial state which lasts as long the object is responsive and remains referenced (by heavy-weighted references). Successor states are unreferenced, terminated, and stopped & alive.

unreferenced

Unreferenced objects are still (at least locally) responsive to allow for terminating operations. All light-weighted references are to be removed to allow the object to be collected. Successor states are terminated and stopped & unreferenced.

terminated

Terminated objects are no longer operational. Note that in case of proxy objects termination does not mean that the original object is no longer accessible. This state has no successor states.

stopped & alive

Sometimes objects are not responsive for a limited amount of time in distributed systems. Stopped objects are still considered alive but are unable to process operations. Successor states are alive, unreferenced, and stopped & unreferenced.

stopped & unreferenced

In some rare occasions it may happen that objects are not responsive during the short time between being unreferenced and terminated. Successor states are unreferenced and terminated.

Explicit state changes are signaled by Notify. Valid values of state are terminated, communicationStopped, and communicationResumed. While terminated is always an absolute state change, the other two work relative, e.g. communicationStopped causes a state change from alive to alive & stopped, or from unreferenced to unreferenced & stopped. Note that state ``changes'' get silently ignored when the current state remains constant (e.g. notifying communicationResumed to an object which is already alive), or when they are illegal:

• unreferenced is signaled implicitly by Detach only, and
• terminated objects do not accept any further state changes.

TakeInterest allows each interested party to get notified about all state changes (whether explicit or implicit) of resource. Note that eventType is even non-NIL if resource is already terminated and no further notifications are to be expected.

DependsOn states that dependant depends entirely on resource. This is usually the case for proxy or filter objects where operations on dependant are delegated or filtered to resource. Only one call of DependsOn may be issued for each dependant while several calls for one resource are valid. DependsOn calls Attach (see below) implicitly for resource and detaches when dependant becomes unreferenced or terminates. All subsequent state changes of resource will be propagated to dependant. The dependency relation will be released when resource terminates or dependant becomes unreferenced or terminates. Because of these implicit attachments, resource cannot become unreferenced as long all its dependants neither become unreferenced nor terminate.

Attach marks resource as being used until Detach gets called. To check for proper nesting of Attach and Detach, a key is returned by Attach which must be passed to the corresponding Detach. Calls of Detach with an invalid key are silently ignored. The last call of Detach causes a state change to unreferenced and undoes a former call of DependsOn (with resource in the role as dependant).

Following operations allow to check for the current state of a resource. They do not distinguish between alive and unreferenced resources:

Alive

returns TRUE if resource is not yet terminated and ready for communication (alive or unreferenced).

Stopped

returns TRUE if resource is currently not responsive but not yet terminated (stopped & alive or stopped & unreferenced).

Terminated

returns TRUE for terminated resources (terminated).

DIAGNOSTICS

SEE ALSO

Events

handling of events

RemoteObjects

support of Resources for distributed objects

Oberon || Library || Module Index || Search Engine || Definition || Module