gk_lockmanager(3gk)

NAME

gk_lockmanager - a distributed locking mechanism

SYNOPSIS

gk_lockmanager lockMgr

DESCRIPTION

The locking layer serves as a mechanism to manage locking data for clients in a GroupKit conference. In most applications, one lock manager is created per conference. The lock manager is a very simple environment that stores the lock name and related information. All locks are managed through the lock manager. In addition to the standard operations on locks, a conflict detection procedure for lock names can be specified on a per manager basis.

An instance of a lock manager is created with the gk_lockmanager command, which specifies a name for the lock manager. This creates a lock manager command, similar to Tk's widget commands, which are used to manipulate the lock manager.

LOCK MANAGER COMMAND

The gk_lockmanager command creates a new Tcl command whose name is lockMgr. This command may be used to invoke various operations on the lock manager. It has the following general form:

The following subcommands are defined for lock managers:

lockMgr request name callback ?timeout?

Request a lock named name. This command returns immediately, before the lock request is complete. The result is obtained through the callback which is a Tcl command that takes as its last parameter the word "Succeeded" or "Failed". If the lock is not granted with the timeout period, the callback is executed with the value "Failed".

The request command also returns a transaction identifier for the pending request that can be used by the status command to query the state to the request.

lockMgr release name

Release the lock named name. Again, this command returns immediately. Your program will not receive notification when the lock has actually been released.

lockMgr status identifier

Query the current state of the request for the transaction identifier. The transaction identifier can be obtained from the return value of the request command. The status command returns the values "Succeeded", "Failed" and "Pending".

lockMgr owner name

Return the user number of the owner of the lock name. If the lock is not found, then the empty string is returned.

lockMgr locks

Returns a list of the current locks.

lockMgr setconflictproc command

Customize the conflict detection scheme for the locking data. If a conflict is detected, this command must return the value 1, or the value 0 otherwise. The default scheme is to assume that two locks having the same name conflict, and two locks with different names don't conflict. This hook may be used to provide a more sophisticated scheme, such as for overlapping locks in a text buffer.

lockMgr destroy

Destroy the lock manager, its associated data, and the lock manager command.

NOTES

The locking mechanism described here is a storage and retrieval system designed to maintain information about a set of locks. This provides an underlying, independent data structure for the creation of more complicated locking mechanisms, in applications such as a GroupKit user interface.

In the underlying implementation, lock requests are serialized through a single GroupKit conference process. Every other conference process keeps a local cache of the existing locks. Requests to change locks (e.g. request, release) will be sent to the serializing process, while state queries (e.g. locks, owner) are executed locally by examining this cache.

AUTHOR

Terrence Asgar-Deen ([email protected])