The shared object package is designed to complement Network objects. A network object allows an object to be shared by multiple processes, possibly on different machines, by creating surrogate objects in all processes except the one in which the object actually exists. From the point of view of the programmer and the executing program, the surrogate object behaves exactly like the original object. However, all method calls to the surrogates are synchronously sent to the original object where they are executed, with return values or exceptions propogated back to the calling process.

For many applications, this is sufficient and has many desirable properties: there are no sychronization issues, calls are synchronous so exceptions propogate across processes, global garbage collection is performed, etc. However, for some applicates, the paradigm is not appropriate. The sychronous nature method calls restricts the frequency and of checking the object for changes. More seriously, interested parties are restricted to polling an object if they are interested in changes. Finally, all operations on an object, no matter how trivial, require a remote procedure call, which takes a significant amount of time.

To address these problems, and others, the shared object package was created. The model is the opposite of the network object package and is intended to complement rather that replace it. Instead of the object being stored at one location and remote method calls being used to access the object, shared objects are fully replicated in all interested processes, with any updates to the object being applied to all copies.

\section{Differences between Shared and Network Objects}

The easiest way to explain the shared object package is to compare it to the network object package. In order to support full replication, there are some important behavioural differences between network and shared objects. In the discussion below, update methods refer to methods which change the internal state of an object. The local copy is the copy that resides in the process in which the method call is made.

\begin{list} \item Methods which update the shared object are applied to all copies of the shared object. It is important to realize that the actual method is called at all sites. The shared object package guarantees that all updates will be applied to all copies of an object in the same order, but makes to guarantees about the specific order of application of two method calls performed at approximately the same time. \item In order to provide the above guarantee, update method calls are not performed immediately on the local copy of an object. The caller will block until it is time for the update to be performed, then will be unblocked, perform the update, and return. \item Restrictions are placed on the kinds of parameters that can be used with update methods, due to the requirement that these parameters be distributed to all copies so the update method can be applied everywhere. Specifically, network objects, shared objects, data streams (subtypes of Rd.T or Wr.T) and any object that is associated with a particular process should not be used. (The restriction on using network objects and shared objects as arguments to update methods may be lifted someday if absolutely necessary). \item Network object method calls are performed synchronously. Thus, values can be returned and exceptions propogated back to the original site. Shared object update method calls are performed synchronously on the local copy, but asynchronously on all other copies. Thus, return values and exceptions (except the SharedObj.Fatal exception, as described below) are ignored in all copies except the local one. \item Non-update method calls are performed immediately on the local copy. Thus, read access to shared objects is significantly faster that to network objects. \item Since network objects exist at only one location, programmers are free to create subtypes of network objects which still appear as the original network object when sent out over the network. This works because the network object stub generator only generates the surrogate objects that stand in for the object on remote machines: the real object is not changes. Shared objects, on the other hand, must not be subtyped, as the shared object stub generator generates an object which encapsulates the original object, overriding all methods to create the desired behaviour. If subtypes are created and distributed, incorrect behaviour may result. \item Network objects provide no way for anyone with a copy of the network object to be notified when it changes. It is straightforward to add this to a specific network objects explicitely in exactly the same way as one would do it to any other objects. All shared objects, on the other hand, have change notification built in via Callback objects. When a shared object is generated with the stub generator, a corresponding callback object is generated, as described below. \end{list}.

\section{The Shared Object Package}

The primary public interface for using shared objects is described here.

INTERFACE SharedObj;

IMPORT Atom, AtomList, Thread, EventNumber, EmbProxiedObj, Wr,
       Pickle2 AS Pickle, Rd;

CONST Brand = "Shared Objects v.1";

TYPE
  T <: Public;
  Public = EmbProxiedObj.T OBJECT END;

  PROCEDURE Init(s: T): T;

TYPE Code = AtomList.T;

EXCEPTION Error(Code);           (* Error condition. *)
EXCEPTION Fatal(Code);           (* Fatal error condition. *)

It is very important that these exceptions be used correctly. Using Error when Fatal should be used will result in copies of the objects being out of sync. Using Fatal when Error would suffice will result in unnecessarily invalidating a copy of the object. Obviously, it is safer to err on the side of raising Fatal too often rather than too little.

VAR                              (*CONST*)
  CommFailure, NetObjFailure, NetObjAlerted, EventFailure, DeadObject,
  Alerted, RecursiveUpdate, IPFailure: Atom.T;

TYPE
  Callback = EmbProxiedObj.T OBJECT END;

TYPE SequenceNumber = EventNumber.T;

The sequence number is the same as an event number. Each update to an object is assigned a sequence number. Users of the package do not currently need to know about sequence numbers.

In order to provide control over shared objects, the following routines are provided.

PROCEDURE Wait(obj: T; c: Thread.Condition; m: Thread.Mutex := NIL);

It is important that a thread not needlessly block while inside a SharedObj method call. If a thread wishes to wait on a condition variable, it should call Wait instead of Thread.Wait. If no Mutex m is supplied, the implicit mutex is used. The calling thread must have m locked if it is supplied.

PROCEDURE AcquireGlobalLock (obj: T) RAISES {Error, Thread.Alerted};

PROCEDURE ReleaseGlobalLock (obj: T) RAISES {Error, Thread.Alerted};

PROCEDURE Own (obj: T; willingness: Timeliness := 0)
  RAISES {Error, Thread.Alerted};

However, if one client will be doing most, or all, of the updating of an object, it is not necessary for their update method calls to incur this overhead. The Own(obj,willingness) calls declares the local process to be the owner of shared object obj, and the willingness of the local process to provide direct updates to other processes (see the discussion of Timeliness below). Declaring ownership has a number of side effects: \begin{list} \item The ordering of update events will be performed in this process, significantly reducing the time require for update method calls to complete in process. The time is now comparable to a non-update method call. Unfortunately, the time required for other processes to perform update method calls will be increased somewhat. \item Acquiring and releasing the global lock is significantly faster (analogous to the speed improvement for update method calls). The time required for other processes to acquire and release the global lock will be increased somewhat. \item Network traffic may be reduced for updates performed by this object. \item The time required for updates made by this process to reach certain other copies may be reduced (see the discussion of Timeliness below). \end{list}

PROCEDURE Disown (obj: T) RAISES {Error, Thread.Alerted};

TYPE Timeliness = [-8 .. 7];

PROCEDURE SetTimeliness (obj: T; value: Timeliness)
  RAISES {Error, Thread.Alerted};

Timeliness values are currently used when some process declares itself the owner of obj. When declaring ownership, a willingness value is provided. Any copy of the object with a timeliness greater than this willingness value will receive updates directly from the object. As a result, declaring a timeliness of FIRST(SharedObj.Timeliness) will prevent the process from ever receiving updates directly. Similarly, declaring a willingness of LAST(SharedObj.Timeliness) will prevent a process from ever sending udpates directly. Any other combination is obviously possible.

\paragraph{Specials.}

Specials provide for customized pickling of specified data types on every call of read or write in this process. See the Pickle package for the details on Pickle.Specials. The Shared Object system uses the Pickle package to transmit data between hosts, by registering a Pickle.Special for each subtype of SharedObj.T. A SharedObj.Special may be registered for a specific subtype of SharedObj.T and is used by the type's corresponding Pickle.Special routines to read and write the user defined data for that object. By default, all of the user defined data fields of a SharedObj.T are writen and read. As with Pickle.Specials:

\begin{itemize} \item the methods must leave the Rd.T or Wr.T positioned after the last byte read or written;

\item the read method must consume the number of bytes written by the write method;

\item the read method must produce a value equivalent to the one that was given to the write method. \end{itemize}

If these rules are violated, the result could be either a checked runtime error or an invalid result from reading a pickle.

There are many ways to program a special. For example, the write method could modify the value and then call the root special. Or the write method could create a related value and call writer.write or Special.write. Or it could write some data fields individually and call writer.write for selected sub-values of its value. Or it could use mixtures of these techniques.

The SharedObj.Special methods cannot be called themselves. Each SharedObj type will have its own subtype of Special generated, whose default methods will read and write the user defined fields of the object. Each type will also have it's own RegisterSpecial(sp) procedure defined, to set the special to be used for that type.

TYPE
  Special = OBJECT
    METHODS
      write(obj: T; writer: Pickle.Writer)
        RAISES {Pickle.Error, Wr.Failure, Thread.Alerted};
      read(obj: T; reader: Pickle.Reader)
        RAISES {Pickle.Error, Rd.EndOfFile, Rd.Failure,
                Thread.Alerted};
    END;

END SharedObj.

      TYPE
           Data = Logitech.TrackerPosition;
           T <: S;
           S <: Public;
           Public = SharedObj.T OBJECT
         		METHODS
         		  set (READONLY val: Data) RAISES {SharedObj.Error};
         		  get (VAR val: Data) RAISES {SharedObj.Error, Thread.Alerted};
         		  <* SHARED UPDATE METHODS set *>
         		END;

      TYPE
           T <: Public;
           Public = SharedObj.Callback OBJECT 
             METHODS
               init(obj: TrackerPosition.T): T;
               pre_set (READONLY obj: TrackerPosition.T; 
                        READONLY val: TrackerPosition.Data): BOOLEAN;
               pre_anyChange(READONLY obj: TrackerPosition.T);
               post_set (READONLY obj: TrackerPosition.T; 
                         READONLY val: TrackerPosition.Data): BOOLEAN;
               post_anyChange(READONLY obj: TrackerPosition.T);
             END;

      TYPE
           MyCallback = T OBJECT 
               left: BOOLEAN;
             OVERRIDES
               pre_set := MyPreSet;
               post_set := MyPostSet;
               post_anyChange := MyPostAnyChange;
             END;
         
         PROCEDURE MyPreSet(cb: MyCallback; READONLY obj: TrackerPosition.T; 
                            READONLY val: TrackerPosition.Data): BOOLEAN =
           BEGIN
             left := obj.getLeftButton();
           END MyPreSet;
         
         PROCEDURE MyPostSet(cb: MyCallback; READONLY obj: TrackerPosition.T; 
                             READONLY val: TrackerPosition.Data): BOOLEAN =
           BEGIN
             IF left # obj.getLeftButton() THEN
               IO.Put("Left button changed!\n");
               RETURN TRUE;
             END;
             RETURN FALSE;
           END MyPostSet;
         
         PROCEDURE MyPostAnyChange(cb: MyCallback; 
                                   READONLY obj: TrackerPosition.T) =
           BEGIN
             IO.Put("Something other than the left button changed.\n");
           END MyPostAnyChange;

      TYPE
           MyCallback = T OBJECT 
             OVERRIDES
               pre_set := MyPreSet;
               pre_anyChange := MyPostAnyChange;
             END;
         
         PROCEDURE MyPreSet(cb: MyCallback; READONLY obj: TrackerPosition.T; 
                            READONLY val: TrackerPosition.Data): BOOLEAN =
           BEGIN
             IF val.left_button # obj.getLeftButton() THEN
               IO.Put("Left button changed!\n");
               RETURN TRUE;
             END;
             RETURN FALSE;
           END MyPreSet;
         
         PROCEDURE MyPreAnyChange(cb: MyCallback; 
                                  READONLY obj: TrackerPosition.T) =
           BEGIN
             IO.Put("Something other than the left button changed.\n");
           END MyPreAnyChange;