Remote Consulting via TANGO in XEmacs
Northeast Parallel Architectures Center
Introduction
Both TANGO shared editor and TANGO shared debugger modules require XEmacs 19.15 or newer. They should work with FSF Emacs 19.34 or newer, however slight modifications of the code might be required. As of May 1998, XEmacs support for MS Windows 95/NT is still in beta phase, therefore shared editing via TANGO in XEmacs is possible only between UNIX architecture clients. Similarly, TANGO shared debugger is based on (X)Emacs gdb mode, and thus will run only on platforms GNU gdb is supported on, which are all popular UNIX architectures.
However, when a version of XEmacs for MS Windows 95/NT appears, shared editing between collaborators running TANGO on any platform will be possible. Shared debugging will let inspect applications run on Unix workstations remotely by TANGO users working on PC’s. Remote control and debugging of Windows applications will depend on availability of GNU gdb on MS Windows.
It is assumed that users of TANGO shared XEmacs know how to use XEmacs, and are familiar with XEmacs related terms such as region, buffer, face, and alike. For customization of TANGO shared XEmacs, basic knowledge of Emacs LISP is required.
Installation
The whole installation necessary for TANGO XEmacs shared editor and shared debugger modules is just downloading the archive from:
http://www.npac.syr.edu/users/remek/cewes/XEmacs-shared.tgzand unpacking it to the appropriate location, determined by the value of the TANGO_APP_ROOT environment variable. This can be achieved by issuing the following commands:
cd $TANGO_APP_ROOT
gunzip –c /tmp/XEmacs-shared.tgz |tar xvf –
assuming that the archive has been downloaded to /tmp/XEmacs-shared.tgz. No changes to the PATH environment variable are necessary, provided that ‘xemacs’ command is available. No changes to XEmacs load-path are necessary either—TANGO XEmacs shared modules are capable to determine locations of all ELISP files from the value of TANGO_APP_ROOT environment variable.
Contact
Please send any questions and comments on Tango XEmacs modules and related issues to Remek Trzaska <remek@npac.syr.edu>.
Shared Editing
Collaborative Writing
Collaborative writing systems have been divided into three categories: synchronous, where writing by different authors takes place at the same time; asynchronous, where only one person controls the entire document at a particular moment; and semi-synchronous systems, where authors are able to work together on different sections of the same document at the same time. When implementing shared editor for TANGO, we decided to implement it as a semi-synchronous one. This approach both provides reasonable cooperation capabilities, and is not very demanding as far as network bandwidth goes.
A typical collaboration session using TANGO shared XEmacs starts with opening a new or existing file and selecting by different users regions each of them is going to edit. After a user gains lock of a region, he/she may edit it as in any text editor. The user decides when to send updates of the region he/she holds lock for. When the user finishes editing the region, he/she releases it, so that others can review it.
Registering Document to Be Shared
Before a document can be edited in a collaborative way, it has to be registered in TANGO XEmacs. The command
tg-edit-register-file (by default bound to C-c t r) is meant to perform this task. It is interactive and takes one argument, which is a name (either relative to current directory or absolute path) of the file to be registered for collaborative editing via TANGO.Note: If either a non-existing or an empty file is registered, TANGO XEmacs will automatically insert a single newline character at the beginning of the file. This is required to let the user select any region for locking.
Locking Region for Modifications
Initially, just after opening a file, all of its contents is not available for modification. A special command,
tg-edit-add-region (C-c t a) has to be issued on a selected region that will lock this region, register it in TANGO XEmacs, and permit the owner of the lock to perform editing operations. First, tg-edit-add-region checks if the selected region is not overlapping any other TANGO regions. If the region selection is legal, read-only property is removed from the region. Then, visual features, such as face and balloon help property are set, and finally an appropriate message is sent to other participants.Other participants in response to this type of message display the region with special face and set the balloon help property of the region to a text "locked by ownername."
Modifying Regions
A locked TANGO region is open for modifications by its owner (a user who holds the lock). Those operations include all typical editing functions, such as insertion, deletion, replacements, etc.
A command
tg-edit-delete-region, bound to C-c t d, removes the contents of a TANGO region.Note: It is crucial for consistency of distributed copies of a shared file not to remove the entire TANGO region with ordinary deletion operations. These operations remove the XEmacs extent, which identifies TANGO region, and thus commit and release operations cannot be performed successfully. TANGO region, once entirely removed from the file cannot be restored by
undo command. To remove a TANGO region, use tg-edit-delete-region command (C-c t d) only.Committing Changes
To preserve bandwidth and improve performance, TANGO region changes introduced by editing operations are not transmitted to other session participants immediately. When the owner of a TANGO region lock decides to update others’ copies of the shared file, he/she issues a command
tg-edit-commit-region (C-c t c). This command requires the point to be inside a TANGO region belonging to the person who issues it.Releasing Regions
After a user has finished modification of a region of the shared file, he/she is supposed to release it, so that other participants may gain the lock over any fragment of it. This is accomplished by a command
tg-edit-release-region (C-c t l), which similarly to tg-edit-commit-region requires the point to be inside of the region.Note: a TANGO region has to be committed before it can be released.
Unregistering Files
Since every participant of shared editing session stores his/her own copy of the shared file, his/her closing of a TANGO buffer does not affect other collaboration parties. The only operation performed by TANGO XEmacs is automatic committing and releasing of all the regions locked by the participant who is closing the TANGO buffer. These actions are performed automatically when any standard XEmacs buffer removal operation is invoked on a TANGO buffer.
Killing XEmacs
TANGO XEmacs substitutes the key that is bound to the command
save-buffers-kill-emacs with its own function, tg-exit-emacs. This command unregisteres all the TANGO buffer the user shares with others participants (what results in losing all region locks). If the user who is about to close XEmacs is the master of the TANGO XEmacs session, a special notifying message is sent to others. After a while necessary to deliver this message, the socket connection to TANGO demon is closed, and the usual process of closing XEmacs is carried on by calling the command save-buffers-kill-emacs.Customization
Most likely, every user will want to change properties of faces used to display a locally locked region and a face used for remotely locked region to adjust them to the background color he/she uses. The defaults for these faces are:
(set-face-background ‘tg-locked-here-face "NavyBlue")
(set-face-background ‘tg-locked-others-face "grey40")
Default keybindings for TANGO XEmacs shared editing operations start with C-c t prefix and are following:
(global-set-key [(control c) t r] ‘tg-edit-register-file)
(global-set-key [(control c) t a] ‘tg-edit-add-region)
(global-set-key [(control c) t c] ‘tg-edit-commit-region)
(global-set-key [(control c) t d] ‘tg-edit-delete-region)
(global-set-key [(control c) t l] ‘tg-edit-release-region)
These defaults can be changed according to user’s preference. To make the changes permanent, appropriate LISP forms should be placed in user’s own .emacs file.
Screenshots
Shared Debugging
Mode of Operation
TANGO shared debugger extends functionality of traditional tools for tracing programs and fixing bugs to fully collaborative mode. It lets one user start a process on his/her machine under GNU gdb debugger in (X)Emacs gdb mode, and afterwards grant full control over this process to any participant of the collaboration session. Other participants may run TANGO on any hardware/software platform that supports both XEmacs and TANGO. We will refer to the person who initiated the debugging process by issuing the command
gdb as a debug process owner.To exemplify, a session may be established between a debug process owner running TANGO on a high-security SGI mainframe, and a programming expert connected from a SUN workstation. This collaboration may result in fixing serious software problems thanks to knowledge and experience of the expert without the need for expensive travel or risk of opening an account for an outside user. Every action of the remote user is monitored in the debug process owner XEmacs buffer, and in emergency debugging process can be killed by him/her instantly.
TANGO XEmacs shared debugger fully supports master/slave changes. Any of the participants at any time can ask to become a master, and if approved, gain control over the debugging process.
Starting a Session
TANGO XEmacs shared debugger is integrated with XEmacs gdb mode. The mechanism of ELISP "advices" allowed us to modify behavior of gdb mode commands without changing their names, so that everyone who knows how to debug code with help of (X)Emacs gdb mode is immediately able to use TANGO XEmacs shared debugger.
A new debug process is initiated with
M-x gdb command. This creates a dedicated buffer with output of both GNU gdb program and the application being debugged. Content of this buffer is shared among all participants of the TANGO XEmacs shared debugger session. Current master of the session enters commands for the debugger in this buffer.Whenever the regular XEmacs gdb mode is able to display a source code line corresponding to the current frame it pops up a buffer with this line highlighted. The same functionality is provided by TANGO XEmacs shared debugger. Source files are transmitted from debug process owner’s filesystem to other session participants. When the file is received, TANGO XEmacs shared debugger stores it in a temporary directory defined as /tmp/TANGO-shared-debugger.
Pitfalls
Sending commands to debugger process running on a remote machine is initiated by pressing return or enter key. This command always takes the contents of the last line of the buffer, possibly removes the debugger prompt "(gdb)", and sends it to debug process owner. It happens sometimes that the debugger puts in this line some text by itself, such as questions (e.g. "The program is already being run. Restart it? (y on n)"). If the user inserts the answer in the same line, debugger will receive the whole line instead of just the text typed in by the user. In such situations, the user must first start a new line, by pressing
C-u return, and then answer with single letter y or n.
Screenshots
TANGO API for XEmacs Lisp
Creating and Sending Messages
Constructs a message string from TYPE and DATA. TYPE can be either
tg-control or tg-data. Header of the message is four-byte representation of TYPE. Treatment of BODY argument depends on the type of the message. For control messages, BODY is expected to be an integer corresponding to one of known message types. For data messages, BODY should be a list of integers and/or strings.Sends MESSAGE to Tango CA using
tg-connection. MESSAGE is a string usually constructed by tg-create-message function.Responding to Control Messages
The following functions have been defined to respond to standard control messages. The user is not supposed to use these functions directly, since they are called by
tg-process-filter. Additional behavior can be added to the control message respond functions by means of hooks.Default action
: sets tg-masterp to t or nil depending on the new mastership status.Available hooks:
tg-slave-to-master-hooks
: run when a slave becomes a master,tg-master-to-slave-hooks
: run when a master becomes a slave,tg-initialize-master-hooks
: run when a new participant becomes a master,tg-initialize-slave-hooks
: run when a new participant becomes a slave.Hooks arguments: none
Default action
: sets tg-username-string to a string received from Tango CA.Available hooks:
tg-respond-username-hooks.Hooks arguments: none (user's name can be determined from a value of
tg-username-string).Default action
: sets tg-mastername-string to a string received from Tango CA; displays a message stating the master's name in the current XEmacs session.Available hooks:
tg-respond-mastername-hooksHooks arguments
: none (master's name can be determined from a value of tg-mastername-string).Default action
: sets tg-hostname-string to a string received from Tango CA; displays a message stating the name of the host the current Tango session is running.Available hooks:
tg-respond-hostname-hooks.Hooks arguments: none (host's name can be determined from a value of
tg-hostname-string).Default action
: sets tg-participants-list to a list of all the participants of the current session of Shared XEmacs; displays a message listing them.Available hooks:
tg-respond-participants-hooks.Hooks arguments: none (list of participants can be taken from
tg-participants-list).Default action
: sets tg-activeusers-list to a list of all the users of the current Tango session; displays a message listing them.Available hooks:
tg-respond-activeusers-hooks.Hooks arguments: none (list of active users can be taken from
tg-activeusers-list).Default action
: sets tg-localapps-list to a list of all the local Tango applications that are running on the machine the Tango session has been started; displays a message listing themAvailable hooks:
tg-respond-localapps-hooks.Hooks arguments: none (list of local applications can be taken from
tg-localapps-list).Default action
: raises the current XEmacs frame.Available hooks: tg-respond-focus-hooks.
Hooks arguments: none.
Default action
: sets tg-participants-and-addresses-list to a list of all the participants of the current Shared XEmacs sessions with the addresses of the hosts they are using to connect to Tango; displays a message listing the content of this list.Available hooks:
tg-respond-participants-and-addresses-hooks.Hooks arguments: none (list of participants and their addresses can be taken from
tg-participants-and-addresses-list).Responding to Data Messages
Tango should be notified of all possible data messages and their respective handlers via the value of
tg-data-message-handlers. This variable should be an alist. Each element should be a dot pair of the form (value . handler), where VALUE determines data message type and is a short integer, and HANDLER is a function to be called when a message of this particular type is delivered from Tango CA. Adding a message type and its handler can be performed by a form similar to:
(push '(100 . tg-ee-respond-register-file) tg-data-message-handlers)
Each of handlers is provided with the content of the data message as a list (see
tg-create-message).Registering Application
Establishes the connection with Tango CA on the machine determined by
tg-host (usually the same machine XEmacs is running on), on the port PORT, with application id ID. Resets the value of tg-string. The parameters ID and PORT are obtained usually from Tango CA.Constants
The following constants have been defined
(defconst tg-ismaster 1)
(defconst tg-username 2)
(defconst tg-mastername 3)
(defconst tg-hostname 4)
(defconst tg-participants 5)
(defconst tg-activeusers 6)
(defconst tg-localapps 7)
(defconst tg-focus 122)
(defconst tg-participants+addresses 123)
(defconst tg-participants+addresses-rq 124)
(defconst tg-yes 10)
(defconst tg-no 11)
(defconst tg-terminate 12)
(defconst tg-control 30)
(defconst tg-data 31)