| << Prev | - Up - | Next >> |
GlobalStore Module Application Programming Interface The interface functions to use the GlobalStore module are the followings:
GlobalStore.new {GlobalStore.new ?GS}
Creates a new global store GS where GS can be executed at any site using the following call:
newLocal {GS newLocal(Module UserName ?UserId ?NewObj ?LocalStore ?MoveHere)}
Creates a new LocalStore i.e. connect to Global Store. Each LocalStore can be used again by another site to connect to GlobalStore.
A local store is a single site's reference into the global store.
the GS and newLocal calls can be executed on any site.
Module is the ressource Module Manager in the system.
UserName is an atom or a string identifying a user.
UserId is a unique identifier given to a user.
NewObj is a sited reference; it can be executed only on the site on which it was created. Used to add a new object to the store.
LocalStore is sited except for the newLocal method , which can be executed on any site.
MoveHere is a non-sited reference; it can be executed on any site to move the server to that site.
The call new throws a gs(failed_globalstore_creation) exception when no global store is created.
A LocalStore created by one of these calls can itself create more LocalStores, and so forth recursively. That is, the creation of LocalStores is fully decenralized.
The call newLocal throws a gs(connectionfailed) exception if it fails to connect to the global store.
NewObj O={NewObj Class Init}
Add a new object O to the store. The call NewObj is synchronous. O is an object reference in the global store that is uniquely identified. The new object is immediately broadcasted to the other clients. Object can refrence to other object in the store. Class is any Oz class with the following restrictions:
getuniqueobjectid($) method is defined by GlobalStore for any object from any class. This call returns Oz name. Example:
X={O getuniqueobjectid($)}
no reference to resources e.g. file system, graphics interfece, objects that are not in GS, cells, variables, ports, etc.
object_query {O Method}
At any time without a transaction one can apply a read only method on O (a method that will not change object state). Applying a method that will change O's state should be called inside a transaction. However, if rhe method invocation will change the object state, this does not change the object itself but affects its copy.
The user interacts with the global store by using transactions:
trans {LocalStore trans(Trans ?Out ?Result)}
Initiates a transaction Trans which is a procedure of one argument.This call is asynchronous. The argument Output is a computed return value in Trans. The argument Result is initially unbound. It is bound to the atoms commit or abort. This argument will be bound as soon as global store determine the transaction state. A gs(ill_formed_transaction) exception is raised when Trans is not a one argument procedure. At a single user, execution of transactions are serialized. The procedure must have the following property:
Transactions have no external references to statful entities, such as objects that are not in GS, cells, variables and ports.
These functions can be called inside a transaction.
apply a method on an object {O Meth}
O is a reference to an object in the store.
waitlocks {LocalStore waitlocks(Objects)}
Wait for locks on Objects: if the locks are not obtained the transaction is aborted.
retrans {LocalStore retrans(Proc ?Output ?TranRes)}
The call retrans confirms all updates of the original (father) transaction that have already committed without waiting its end. The initial transaction result Res is mapped to a new transaction's result TransRes. Initially, the new transaction has the set of objects that its father has.
The user can delete an object from GlobalStore by the following call
The user can disconnect normally from GolbalStore by the following call
GS can migrates by calling the MoveHere procedure. The MoveHere procedure is returned by the newLocal call.
MoveHere {MoveHere Module LocalStore Proc}
The call migrates the global store to the site where the one argument MoveHere procedure is executed. LocalStore is a returned sited reference to the store in the site where the call MoveHere is executed. Module is the ressource Module Manager in the system. Proc is a user defined zero argument procedure. Proc is executed at the site where the call MoveHere is executed.
In order to communicate with user applications, the Golbal Store offers notify procedures of three kinds:
Membership (connection/disconnection) notification, to be executed if there is a user connected/disconnected to/from GS.
Object manipulation notification, to be executed if there are any object creation, update, or deletion. Creation procedures are called upon creation of a GS object. Update procedures are called whenever the state of a GS object is changed coherently. Delete procedures are called whenever a GS object is deleted. One Creation, Update, or Delete procedure can be installed per client and per object.
Recovery notification, to be executed when there is a recovery after server's failure. Every client must install this procedure at his site.
A Notify procedure installed by a client is executed only by that client on its site. Notify procedures must respect the following rules:
A Notify procedure can use in any way any language entity outside of the GS, e.g., resources, ports, cells, or objects that are not part of the GS. There are no restrictions.
A Notify procedure is given a coherent view of the GS, and it may call GS objects in any way. However, any changes done by these calls will be canceled after the Notify procedure exits.
The execution of a Notify procedure is serialized with transaction executions at a client. Therefore, the Notify procedure should not be too time-consuming, as this will delay the execution of transactions at that client.
A Notify procedure may initiate transactions, but it should not wait until a transaction completes. Otherwise, deadlock will occur.
setnotifycreation {LocalStore setnotifycreation(Proc)}
Proc is a user defined one argument procedure executed when another user creates a new object in the global store. Proc is executed on the local store. The argument of Proc is a reference to the new object in the store. a method that not change the object state could be called inside the notification to read the most recent state for the object.
setnotifyupdate {LocalStore setnotifyupdate(Proc)}
Proc is a user defined one argument procedure executed when an object in the global store is updated by other users. Proc is executed on the local store. The argument of Proc is a reference to the updated GS object. This reference can be called with a method that will not change its state.
setnotifydelete {LocalStore setnotifydelete(Proc)}
Proc is a user defined one argument procedure executed when an object in the global store is deleted by other users. Proc is executed on the local store. The argument of Proc is a reference to the deleted GS object. The object only be used temporarily inside the notification.
setnotifymembership {LocalStore setnotifymembership(Proc)}
Proc is a user defined one argument procedure executed when there is a change in the membership (user connected, or disconnected). The argument of this Proc will be the list of current membership (username1#Id1,...username#Idn). Where Username1 is an atom or string issued by the user and Id is globally unique and neverchanges for a user.
setnotifyrecovery {LocalStore setnotifyrecovery(Proc)}
Proc is a user defined zero argument procedure executed when there is a recovery after server's failure and this is only executed at the new server site. To guarantee its execution upon recovery, every user must set this setnotify recovery.
| << Prev | - Up - | Next >> |