Rover Client-Side Tcl Interface

The following Tcl calls are available to Rover client applications:
Rover_LoadApplication // Rover_NewSession // Rover_RPC // Rover_Flush Rover_Flush // Rover_ClientFlush // Rover_QRPC // Rover_PromiseClaim // Rover_WatchApps // Rover_WatchHTTP // Rover_WatchLog // Rover_WatchNet // Rover_Import // Rover_Export // Rover_Shutdown // Rover_StartTimer // Rover_EndTimer // Rover_GetDV // Rover_GetPid // Rover_USleep // Rover_AddFromString // Rover_Escape // Rover_TclEscape // Rover_Unescape // Rover_Info // Rover_IsTentative // Rover_SetAlarm // Rover_CancelAlarm // Rover_ResetSession

There should be documentation of the import and export hook functions.

We explain the following internal procedures in the Rover client library in order to help the application programmer understand the behavior of the library. These calls are NOT meant to be called directly by client applications.
Rover_FinishImport // Rover_FinishExport // Rover_InvokeCallback

Rover_LoadApplication URL args

Loads an application binary, forks, and execs it in its own thread of control and own address space.

URL names the application to be loaded
args are argv to passed to the application when started

Returns a promise for the process identifier of the started application

Rover_NewSession service consistency exclusivity user password

Sets up state in the client to support a session. Calls with identical arguments are return the smae session identifier.

service is the name of the service to which to connect. A service maps to a particular server name and URL to invoke. Services have default mappings in the access manager. These defaults may be overriden by the user's .rover-session-init file.
consistency is the consistency semantics to enforce on the session. Currently only ROVER_NO_CONSIST and ROVER_ACCEPT_TENT have been implemented. The former enforces no constraints, the latter allows the client to receive tentative data. Unimplemented options are ROVER_FULL_CONSIST (which requires all data to be consistent with the server) and ROVER_ACCEPT_PERM (which allows the client to accept only permanent data).
exclusivity sets whether data on this session may be shared. Current supported values are:
- here -- Only this application may use this session
- mh -- Any application on the mobile host may share the session
- world -- UNIMPLEMENTED
user specifies the user name associated with the session. Applications at the server run under this user name.
password is the authenticator for the user. Currently the password is sent in clear text with every request to the server. Therefore, the only password accepted is "foo".

Returns the (integer) session identifier.

Rover_RPC session URL command args

Performs a remote procedure call. The actual semantics of the operation performed depends on the specified command, the status of the object named by URL, and the characteristics of session.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.
command is the string representation of the CMDtype enumeration
args are appended to the object before it is evaluated in the callback

Rover_Flush session URL

Flushes an RDO from the client application's and access manager's caches.

session is an interger identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.

Returns TCL_OK

Raises error if

session is invalid
the RDO named by URL is not in the access manager's cache

Rover_ClientFlush session URL

Flushes an RDO from client cache.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.

Returns TCL_OK

Raises error if

session is invalid
the RDO named by URL is not in the client cache

Rover_QRPC

Rover_PromiseClaim promiseID

Obtains the value of a promise. Blocks until the promised value is available.

promiseID is a promise returned by Rover_LoadApplication,Rover_Import, or Rover_QRPC

Returns the value of the claimed promise.

Rover_WatchApps text_widget

Monitors currently running client applications. Each application is listed by URL on one line in the text widget with an indication of the number of users running that application.

Used by Rover chooser.

text_widget is a tk text widget in which data maybe displayed.

Returns TCL_OK

Rover_WatchHTTP

Monitors HTTP traffic. Formats the cache list as a Tk text widget, with buttons to view, reload, or delete each visible entry. Then, invokes the tcl interpreter to display it.

Used by Rover Web proxy.

Returns TCL_OK

Rover_WatchLog text_widget

Monitors the access manager log. Each (Q)RPC in log is displayed on a separate line listing the session, URL, type of operation, and status. Each priority queue and the queue of operations already sent to servers is listed separately.

Used by Rover chooser.

text_widget is a tk text widget in which data maybe displayed.

Returns TCL_OK

Rover_WatchNet

Monitors the state of the network. Ask the access manager to update the client with the state of the network. The global Tcl variable Rover__Env__netStatus is set to reflect the state of the network. The access manager informs the client of changes in the status of the network every 5 seconds. Currently, the only recognized network statuses are ON and OFF.

Returns TCL_OK

Rover_Import session URL callback

Fetches an RDO into the application. Rover_Import is non-blocking in the sense that control will be returned to the calling context without waiting for the network. However, callback (or any other pending callback) may be invoked before Rover_Import returns.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.
callback is a Tcl script

Returns a promise for the object.

If the RDO is in the access manager's cache and the cacheability of the RDO allows it, the RDO will be returned and the callback invoked without contacting the server. If the RDO is not present, or if cacheability of RDO requires it, the RDO will be fetched (or verified) from the server before the callback is invoked. The last possiblity is that the RDO will be returned and the callback invoked immediately, but a QRPC will scheduled to be completed at the access manager's convenience.

The semantics of session determine if a tentative version of an object may be returned.

Rover_FinishImport

Rover_FinishImport is NOT an available call into the library. We provide this explanation so the application programmer understands what happens as a result of Rover_Import

Some time after a Rover_Import call is issued, the server will respond with an RDO. When the RDO is received in the application from the access manager, the following steps occur:

NOTE: Currently, if Rover finds tentative opeartions associated with an object during Rover_FinishImport, the tentative operations are purged, not replayed. This behavior will go away when the FinishImport and FinishExport paths are merged.

Load the code. The code segment of the object is evaluated in the Tcl interpreter.
Save the unmarshalling function. The value returned by the evaluation of the code segment is treated as a Tcl script for unmashaling the object data.
Fill the promise. The promise for the RDO is updated to return the the return value of evaluating the unmarshall script with the object data.
Load the data. The data segment of the object is assigned to a Tcl variable. The name of this variable is appended to the unmarshalling script and the resulting string is evaluted. If the unmarshalling script is the name of a Tcl function, this works as a function call.
Invoke the callback Rover_InvokeCallback is called with appropriate arguments to evaluate the callback associated with the import.

Rover_InvokeCallback

Rover_InvokeCallback is NOT an available call into the library. We provide this explanation so the application programmer understands what happens as a result of Rover_Import/Export

Evaluates a callback script. The following arguments are appended to the script before it is executed.

value is the return value of evaluating the unmarshall script with the object data.
{serverID, DV} Tcl list of server identifier and server provided dependency vector
RoverType of value

Rover_Export session URL operation unmarshall_script callback

Applies an operation to RDO and reconciles the result of that opeation with the server. Rover_Export is non-blocking in the sense that control will be returned to the calling context without waiting for the network. However, callback (or any other pending callback) may be invoked before Rover_Export returns.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.
opeartion is a Tcl script
unmarshall_script is a Tcl script
callback is a Tcl script

Returns a promise for the object.

Rover_Export performs the following actions:

Inserts an empty object in the application cache, if the RDO is not already present.
Stores the unmarshall_script for later
Evaluates operation in the Tcl interpreter
Marshalls the new tetative state of the object in the interpreter. This action is done by evaluating the Tcl script url marshall. It is assumed that url is a Tcl procedure that takes the argument marshall and returns a string representing the marshalled data of the object. (See Sanjay Ghemawat's class system for Tcl for an example of this approach.) The marshalled state of the object is stored as the tentative data for the object.
Logs operation and callbackin a per-object log
Sends the operation off to the server (via a QRPC).

Rover_FinishExport

Rover_FinishExport is NOT an available call into the library. We provide this explanation so the application programmer understands what happens as a result of Rover_Export

Completes the export and reconciliation process for an operation on an RDO. Some time after Rover_Export is called, the server will return a log of operations that will update the RDO from the permanent state stored in the client (and access manager) cache to the state of the RDO at the server (at the time the log was sent).When the log is received in the application the following steps occur:

Restore persistent copy of object. The (permanent) data segment of the object is assigned to a Tcl variable. The name of this variable is appended to the unmarshall_script and the resulting string is evaluted. If unmarshall_script is the name of a Tcl function, this works as a function call. This operation should overwrite any tentative state of the RDO.o
Apply the log from the server on the object. Invoke callbacks if operations are committed or fail Each operation in the log returned by the server is applied to the RDO. If the operation was originated at this client, the operations is deleted from the object operation log and the callback associated with that operation is invoked by calling Rover_InvokeCallback with appropriate arguments.
Marshall and save new persistent copy of object This action is done by evaluating the Tcl script url marshall. It is assumed that url is a Tcl procedure that takes the argument marshall and returns a string representing the marshalled data of the object. (See Sanjay Ghemawat's class system for Tcl for an example of this approach.) The marshalled state of the object is stored as the permanent data for the object.
Apply the operatoins still in the tentative log on the object. Invoke callbacks if operations fail Each operation in the log associated with the object is (re)applied to the RDO.
Marshalls the new tetative state of the object in the interpreter. This action is done by evaluating the Tcl script url marshall. It is assumed that url is a Tcl procedure that takes the argument marshall and returns a string representing the marshalled data of the object. (See Sanjay Ghemawat's class system for Tcl for an example of this approach.) The marshalled state of the object is stored as the tentative data for the object.
Pass the new marshalled object to Access Manager.

Rover_Shutdown

Shuts down sessions and other soft state of an application held by the access manager for an application..

Unimplemented.

Returns TCL_OK

Rover_StartTimer

Starts a real time timer. Up to MAXTIMERS (1000) timers maybe running simultaneously. (More will overwrite the oldest timers.) Returns an (integer) identifier of the started timer.

Rover_EndTimer timer

Computes real time since timer was started.

timer is an (interger) identifier of a valid timer (e.g. as returned by Rover_SessionTimer)

Returns number of seconds since timer was started. Truncated to four decimal places.

Rover_GetDV session URL

Obtains the dependency vector for an RDO. The vector is the time stamp provided by the server for the last permanaent state of the <RDO.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
URL names an RDO.

Returns dependency vector for RDO

Raises error if

session is invalid
RDO name by URL is not in the client cache

Rover_GetPid appID

Asks the access manager for the process identifier for a Rover application. Block until answer is returned.

appID is an (integer) identifier of a valid application (e.g. as returned by Rover_LoadApplication)

Returns (integer) PID for application

Raises error if unable to send to access manager

Rover_USleep usec

Suspends the client process for the number of microseconds specified by the argument as usleep (3).

usec is (integer) number of microseconds to sleep

Returns TCL_OK

Rover_AddFromString string [priority]

Enters options for tkwin's main window given a string containing lines in the standard format for X resources (see other documentation for details on what this is).The memory at string is totally trashed by this procedure. If you care about its contents, make a copy before calling here.

string cotains X Resource specifications
priority priority in tk database

Returns TCL_OK

Raises error if parsing string fails

Rover_Escape string

Escapes a URL for transmission by substituting a '%' followed by a two digit hexadecimal code for any characters that cannot be transmitted raw. This table lists the characters which are escaped.

string is any string

Returns escaped string.

Rover_TclEscape string

Escapes a string for use as an argument to a TCL procedure by inserting a \ before any special TCL characters. This table lists the characters which are escaped.

string is any string

Returns escaped string.

Rover_Unescape string

Reverses escaping performed by Rover_Escape This table lists the characters which are effected.

string is any string

Returns unescaped string.

Rover_Info infoType session object

Returns information about an object:

Type CodeSize DataSize TDataSize OperCount LogSize DVSize CacheType

infoType is the type of information being requested and is one of: all, type, csize, dsize, tdsize, opcount, lsize, dvsize, or ctype.
session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
object is the URL for an RDO.

Returns information about an object.

Rover_IsTentative session object

Determines if object has tentative (unreconciled) data.

session is an (integer) identifier of a valid session (e.g. as returned by Rover_NewSession)
object is the URL for an RDO.

Returns number of tentative operations on object

Raises error if

session is invalid
object is not in the access manager's cache

Rover_SetAlarm name milliseconds callback

Sets a real time alarm. Up to MAXALARMS (1000) alarms maybe running simultaneously. (Attempts to use more will return an error.) The alarm expires periodically until cancelled by Rover_CancelAlarm.

name is the name of the alarm.
milliseconds is the time in milliseconds until the alarm expires.
callback is the callback to invoke when the alarm expires.

Returns TCL_OK.

Rover_CancelAlarm name

Cancels a previously set real time alarm.

name is the name of the alarm.

Returns TCL_OK if the alarm is defined, otherwise, returns TCL_ERROR.

Rover_ResetSession session command

Passes command to the server for session for execution.

session is the session to use for sending the command.
command is the command to be sent.

Returns TCL_OK, unless the session name is invalid, in which case it returns TCL_ERROR.