Galaxy Communicator Documentation:
Release Notes for Version 2.x
This document briefly lists all the changes from one Galaxy Communicator
distribution to the next for versions 2.x.
Version 2.x is not the current version of Galaxy Communicator.
August 2000: Version 2.1
Core distribution
- Shared object compilation is now supported. See the installation notes. As a result, you may need to
do something slightly different if you're not using Communicator Makefile
templates. See the upgrade
notes.
- The distribution is now provided under an open source license. All copyright notices have
been updated.
- We have dramatically simplified and reorganized the internal Makefile
templates. This change should be completely transparent to existing applications.
- The dispatch server functionality is now deprecated, and should be
replaced by the new listener-in-Hub
capability. Dispatch servers will probably be removed in the 3.0 distribution.
- It is now possible to control the built-in command line argument parsing
in a much more fine-grained manner when you're writing your own main().
See GalSS_DefaultServerArgs()
and the upgrade
notes.
- A number of utility functions inherited from the MIT sls_util
library which are not used in the core distribution have been removed.
- Thanks to MIT, the Hub logger now uses an API call GalUtil_Mkdirp instead
of a shell call to mkdir.
- MIT fixed a bug in #include ordering which was leading to
incorrect macro expansions.
- MIT made changes to the socket code which ensure that servers on machines
which are assigned IP addresses via DHCP will work correctly.
- AT&T helped debug a problem involving the configuration of MITRE's
Windows NT libraries. Substitution functions such as close() are
now defined in Win32 only if the __STDC__ flag is present when the Galaxy
core library is compiled; this helps ensure that these functions are not
defined when other NT libraries define them.
- The timed task loop now supports the notion of idle functions,
which are invoked periodically when there are no tasks to fire.
- MIT has repaired a large number of memory leaks in the Hub executable
involving frames and frame elements which were not being freed. As part of
this fix, the function Gal_DelProp()
now returns a value indicating whether it found an element to delete or not.
- An insidious bug in the Hub under which queued messages would sometimes
be sent to the wrong server has now been fixed.
- MIT fixed a bug in the Hub under which messages in server connection
output buffers were sometimes not being written out in a timely manner (or
being lost).
- The Hub executable now takes the -verbosity command line argument.
- MIT added better support for handling SIGPIPE.
- Servers now support the notion of client
data, which is data associated with a particular dispatch function rather
than a particular connection.
- A bug in incoming brokering which was causing the finalizer not to
be run in some cases has been fixed.
- MIT has added support for automatic logging when the Hub loses its
connection with servers and when it reestablishes it.
- Enhancement. As a consequence of support for the listener-in-Hub
capability, the function GalSS_InitializeServer()
should be replaced by GalSS_InitializeServerToplevel().
Similarly, the function GalSS_ExtractServerArgs()
should be replaced by GalSS_ExtractCmdlineServerArgs().
See the upgrade
notes.
- Incompatible change. MITRE and AT&T discovered a major
logic mistake in the interaction of sockets and the timed task loop on Win32. As a result,
the function GalIO_AddTimedTaskWithIO has been removed, because the timed
task loop needs to distinguish clearly between file I/O and socket I/O. Furthermore,
since select() can't poll file descriptors on Win32, file I/O polling is
not available on Win32. See the new functions Gal_AddTimedTaskWithSocketIO,
Gal_AddTimedTaskWithFileIO,
and the upgrade
notes.
MIT contributions
- The program file setting MODE:
singlethread is now the default. Since MITRE has always recommended using
this setting, this change should not affect any code.
- Incompatible change. In order to ensure the consistency and
timeliness of MIT software, MIT and MITRE have agreed that MITRE will no
longer distribute any MIT servers or application libraries. MITRE will continue
to distribute MIT open source code, such as the Hub scripting library. One
attractive consequence of this new arrangement is that the entire Galaxy
Communicator distribution is now open source.
- Incompatible change. MIT has clarified and slightly
modified the semantics of the special tokens destroy! and none!.
See the upgrade
notes.
- Incompatible change. The effect of SET: and DEL: directives in program file rules
no longer are transmitted in dispatch_to_main.
See the upgrade notes.
MITRE contributions
- The MITRE process
monitor has been significantly enhanced for 2.0, with options for run-time
screen real estate management and built-in support for automatic restarting
of dead servers (so-called "keepalive" functionality).
- Thanks to a number of sites, a number of bugs in the MITRE Oracle
server have been fixed.
- As a consequence of clarifying the distinction between file I/O and
socket I/O polling in the timed task loop, the MITRE stdin
polling utility is now disabled under Win32.
- The double
example now exemplified the new listener-in-Hub capability.
- Since the new listener-in-Hub capability supersedes the old dispatch
function capability, the dispatch function support in the MITRE utilities
has been deprecated for 2.1, to be removed in 3.0.
- The Java
bindings have been modified to work with the new listener-in-Hub capability.
In particular, support for the -contact_hub and -session_id
command line arguments has been added.
- Various changes to Java bindings implementation to improve thread
synchronization.
- Incompatible change. The header update utility, which updated
server headers from version 1.2 to version 1.3, has been removed.
- Incompatible change. To avoid conflicts with the new listener-in-Hub
capability, the (previously undocumented) -session_id command line
argument to the MITRE dispatch server has been changed to -dispatch_session_id.
- Incompatible change. In the Java bindings, references to the
Thread.stop() method have been removed from Server.java and MainServer.java.
Also, the serverClassName field has been added to ServerUI.java. See the
Java bindings.
- Incompatible change. The command line of the (not very well
documented) MITRE frame transducer has been changed, and the (undocumented)
rule format has been completely redone.
- Incompatible change. The MITRE log analysis
tools were completely rewritten and significantly enhanced for 2.0.1p2,
and further bug fixes were added for 2.1.
- Incompatible change. The Java bindings
now require the use of JDK 1.2.x (previously, some versions of JDK 1.1.x
with Swing support could be used).
Full list
of deprecations scheduled for 3.0
Some of these deprecations have been pending since 2.0. All will be removed
in 3.0.
- GalSS_ReadFrameFromHub (use GalIO_CommReadFrame
instead)
- GalSS_GetServerSock (apparently unused; use GalIO_GetCommSocket
instead)
- GalSS_CloseServerSock (apparently unused; use GalIO_CloseCommSocket
instead)
- GalSS_SetHubDisconnect (use GalIO_SetDisconnectCallback
instead)
- GalSS_CloseHubConnection (use GalIO_DestroyCommStruct
instead)
- GalSS_FlushHubWriteQueue (use GalIO_CommFlushOutQueue
instead)
- GalSS_GetServerName (use GalIO_GetServerName
and GalIO_GetCommServerName
instead)
- The functions sls_pp_frame, sls_cpp_frame, sls_pp_object, sls_cpp_object,
and sls_pr_object have been deprecated in favor of GalUtil_PPFrame, GalUtil_CPPFrame, GalUtil_PPObject, GalUtil_CPPObject, and
GalUtil_PrObject.
- GalSS_WriteFrameToHub (use GalSS_EnvWriteFrame
instead)
- GalSS_DispatchViaHub (use GalSS_EnvDispatchFrame
instead)
- GalSS_GetServerData (use GalIO_GetCommServerData
instead)
- The functionality represented by GalSS_ForceReturn and GalSS_EnvForceReturn
will be removed.
- All functionality relating to dispatch servers will be removed, including
- contrib/MITRE/servers/bin/dispatcher
- MGal_InitializeDispatchServer
- MGal_DispatchServerProcessHubConn
- __MGal_HandleConnection
- MGal_FindDispatchUIArgs
- MGal_SetupDispatchUI
- MGal_DispatchUIMain
- GalIO_ReconnectInit
- GalIO_ServerReconnect
- GalSS_HubReconnectInit
- Gal_Value
- Gal_ValueWarnWithKey
- Gal_UnwrapValue
- Gal_GetValue
- Gal_ValueWarn
- Gal_ValueSilent
- Gal_GetServerName, GalSS_GetServerName (use GalIO_GetServerName
and GalIO_GetCommServerName
instead)
- Gal_SetServerName
- GalSS_GetServerSock (use GalIO_GetCommSocket
instead)
- GalSS_CloseServerSock (use GalIO_CloseCommSocket
instead)
- GalSS_SetHubDisconnect (se GalIO_SetDisconnectCallback
instead)
February 14, 2000: Version 2.0.1
This distribution contains a number of bug fixes and small enhancements
which resulted from the use of 2.0.
Core distribution
- MIT identified and fixed a bug in the socket code which accidently
permitted a server to contact itself in Linux. This fix has also been made
in the MIT socket library.
- AT&T reported a bug in which the Hub would fail ungracefully if
a new token arrived with the :tidx slot already set. This bug has
been fixed; :tidx values on new messages are now ignored, as they
should be.
- A bug where dispatch functions were able to overwrite administrative
information has been fixed.
- A small typo in templates/Makefile.stub has been fixed (init.make
-> archos.make).
- Some small errors in the logging
documentation have been fixed, and it has been slightly reorganized for
clarity.
- The deprecated comparison operator % in Hub scripting rules
was unintentionally removed in 2.0. It has been replaced.
- Due to an oversight, the evaluation of parenthesized expressions in
Hub program conditions was never implemented correctly. This has been fixed.
Negations of conditions grouped by parentheses also works.
- Thanks to MIT, the core Communicator library is now thread-safe on
Windows NT.
- Thanks to MIT, a number of tiny inconsistencies in the NT port have
been fixed.
- All references to ftime() have been removed from the distributed source
code, and the compatibility code kindly provided by AT&T has been removed
as well.
- The bug where clean_headers.pl was not being specialized to platforms
correctly has been fixed.
- MIT copyrights have been changed to open source copyrights in the
appropriate places.
- The standard
server arguments now include -verbosity, which is the command-line
equivalent of setting the GAL_VERBOSE
environment variable.
- The function GalSS_RunServer()
previously called exit() when the timed task loop exits, which defeated the
opportunity for the caller to do cleanups, etc. This call to exit() has been
removed. The equivalent problem in the threaded case has also been fixed.
Thanks to MIT for pointing this out.
- The function Gal_TimedTasksLoopExit()
was not fine-grained enough, because some of the pending tasks were being
executed after this function was called. This has been fixed, and the Gal_EndTasks() has
been added for the threaded case. In addition, thread cancellation is now
enabled during the execution of tasks in threaded mode, so that
blocking reads can be interrupted by Gal_EndTasks().
- All Win32 projects define _REENTRANT when compiling executables and
libraries. A new toplevel workspace named GC.dsw has been created for easier
maintainability.
MIT contributions
- MIT identified and fixed a bug in the socket code which accidently
permitted a server to contact itself in Linux. This fix has also been made
in the core socket library.
- MIT has provided minor updates to their GUI server and the dialogue
management library.
- Two toplevel MIT program files, pegasus.pgm and hub.pgm, are no longer
being distributed because they are outdated.
- There is a new MODE: value in the program file, pedantic,
which will force the Hub to exit if it encounters a missing server or operation.
Default behavior is still to warn and continue.
MITRE contributions
- Support for MIT's new FST recognizer has been added to the MITRE run_summit_server
script.
- The process
monitor now interpolates stdout and stderr better.
- The Hub scripting documentation
has been updated to reflect the fact that the test :foo 3 now interprets
the unquoted sequence of digits as a number, not a string.
- Java bindings are now known to compile under JDK 1.2. The distribution
now ships with pre-compiled byte code and galaxy.jar. The system is still
compatible with jdk1.1.x and now uses Swing 1.1, instead of 1.0 - the import
headers have been modified to javax.swing.
- The XML
logfile generation tool has been improved in a number of ways.
- It now does the right thing with multiline string data
- It now recurses on lists in frames correctly
- It now compensates as much as possible for missing operation invocations.
- It has an expanded argument list, and takes either a pathname or a
directory as input - note that the command line has changed substantially
- It now works on logs generated with Communicator versions previous
to 2.0.
- If the user did not provide a LOG_VERSION:, there is
no longer an empty version attribute produced.
- It can now write to a file as well as stdout.
- Fixed a number of bugs in processing message signatures in the Python
and Allegro bindings.
- Fixed a bug in Python, Allegro and C where if reinitialize wasn't
defined, the message signatures weren't reported to the Hub.
- MITRE has provided an expanded suite of
log manipulation tools.
- The new -verbosity argument has been added to the Python
and Allegro bindings (the Java bindings don't have verbosity levels).
Known bugs
- All 2.0 bugs remain with the exception
of the clean_headers.pl bug, which has been fixed. This status report includes
Java audio clipping, which is now a bit more important to fix because there's
genuine interest in Java audio. We'll work with interested sites to fix this.
- Servers and connections do not shut down their sockets when they exit
due to thread cancellation in threaded mode. This should not be too much
of a problem, since the application should exit almost immediately afterward,
but this should be cleaned up eventually.
Omissions and yet-to-be-honored requests
- All 2.0 omissions remain,
with the exception of progress on threading in NT. While the NT port is now
thread-safe, the -thread server argument is not yet supported.
- IBM reported problems with logging resulting from their audio server
not reporting events in real time.
- CMU has requested more transparent access to session keys, and AT&T
has requested better support for retrieving the session's log directory.
- We will soon issue a revised set of logging tools
which expand the annotation rule language, provide for tab-delimited score
output, introduce support for the type_dialogue_state attribute,
support interpolation of human annotations into the automated annotation
file, and introduce new scoring columns for quantity and percentage of silence
within the system turn.
October 30, 1999: Version 2.0
This distribution of Galaxy Communicator features a number of modifications
requested by the community. In addition, it reflects a reorganization of
the archive to support an anticipated open source development effort. This
version of the release notes is organized by section of the documentation,
instead of by section of the code.
"Directory organization"
- All core Communicator libraries and executables are now in the toplevel
src/ and include/ directories. These include the libGalaxy library (an amalgamation
of the three MIT Galaxy Communicator libraries libgalaxy, libgalaxy_io and
libserverstub, as well as the subset of libsls_util which is used in Communicator)
and the Hub executable (excluding MIT scripting).
- The MITRE documentation is now in the toplevel doc/ directory.
- MITRE-specific contributions besides the documentation are now in
contrib/MITRE.
- MIT-specific servers and support libraries (dialogue control, scripting)
are now in contrib/MIT, the directory structure of which corresponds to the
directory structure of the MIT slice of the 1.3 distribution.
- A range of functions originally in libgalaxy have been moved into
the MIT-specific library libGalaxyEnhancements. These functions deal with
the MIT dialogue mechanism.
- A range of functions originally in the Hub have been moved into the
MIT-specific library libGalaxyHubControl. These functions deal with the MIT
scripting control.
"Installing the distribution"
- If you don't set PERL in your configuration file, make will now fail
clearly instead of mysteriously.
- Incompatible change: the core distribution now uses GNU configure, in part, to generate its configuration
files for each platform. The settings you need to modify have been aggregated
into a single file, instead of the three previously required, and users now
have clearer access to a wider range of customizations.
"Running a configuration
of servers"
- Incompatible change: the locations of the executables and MITRE
servers have changed due to the directory reorganization. Also, the GAL_VERBOSE
environment variable supersedes the SLS_VERBOSE environment variable due
to moving a copy of the MIT command line
argument parsing library into the Communicator core library.
"Thread notes"
"Overview: invocation,
execution summary"
- There is a new command line argument -locations for the Hub executable which is a string
which is a space-delimited sequence of server declarations of the form <server>@<host>(:<port>),
which override the host (and perhaps port) declarations in the Hub script.
- The Hub also accepts the -validate command line argument,
which dynamically validates each message sent to servers, as well as the
status of messages to be returned to servers.
- Incompatible change: the handling of the construction of the
initial token and reinitialize message
has been rationalized. In general, the -init command line argument now
takes precedence over INIT: and
INITIAL_TOKEN:, which
takes precedence over default global information in the program file. In 1.3,
the precedence order for the two was inconsistent.
- Incompatible change: the Hub no longer has a default for the
program file. The -pgm_file argument is now obligatory.
"How to write Hub scripts"
MIT program files now accept the syntax <server>@<host>(:<port>)
as an argument of the SERVER:
declaration.
It is no longer necessary to use DISPATCH_PORT: to identify a server
as a dispatch server. You can pass the :is_dispatch key from the server to
the Hub.
Incompatible change: the handling of the construction of the
initial token and reinitialize message
has been rationalized. In general, the -init command line argument now
takes precedence over INIT: and
INITIAL_TOKEN:, which
takes precedence over default global information in the program file.
"Using the Hub in scriptless
mode"
- MIT program files no longer require
programs. Any messages sent to the Hub which are not handled by the scripting
module are sent to whatever servers implement them. This implements scriptless
interaction (and partial scripting). As a corollary, the initial token is no longer
created implicitly if there is no program named main.
"(How to...) Add a server"
- The header galaxy/galaxy_all.h
now includes all relevant headers and C++ conditionalizations, and is now
the preferred way of specifying Communicator headers.
- Servers now accept multiple simultaneous connections. Server declaration
files now recognize the GAL_SERVER_MAX_CONNECTIONS() macro, and servers accept
the -maxconns command line argument. See the documentation on adding a server.
- Server declaration files now recognize the GAL_SERVER_OP_SIGNATURE()
macro to specify the array of input and output keys, value types, etc. for
dispatch functions, and servers accept the -validate command line
argument which will check each call to a dispatch function against its signature.
See the documentation on adding a server.
- The function _GalSS_init_server()
no longer needs to be defined, since there is now a default in the core library.
- The reinitialize
message no longer is required to return a frame; this requirement is now enforced
by the server library. If the reinitialize message does not provide a frame,
a dummy frame will be sent instead.
- The administrative information (token index, session ID, etc.) in
the frame sent to a dispatch function is now cached and inserted into the
response. It is no longer necessary to return the same frame that was passed
in in order for this information to be passed back to the Hub correctly.
- The Hub now supports remote error reporting (see the function GalSS_EnvError). This
necessitates some slight complications in server-to-server subdialogues, supported
by the new function GalSS_EnvDispatchFrame.
- Incompatible change: relevant MIT functions in libsls_util
have been imported into the core libGalaxy library. These symbols include
the MIT socket library (sock_...),
the MIT command
line argument parsing library (oa_...), and the MIT printing library (sls_...).
Servers no longer link against libsls_util by default, and as a result all
such symbols must be changed. The equivalence table can be found here.
Also, the environment variable which controls the verbosity of printing is
now called GAL_VERBOSE, not SLS_VERBOSE. If you choose, you may also link
against the MIT libsls_util library and keep the old functionality; the symbols
will not clash, and SLS_VERBOSE still controls the verbosity in MIT libsls_util.
- Incompatible change: the header file sls/util.h will no longer
be in the default Communicator include path, because it's no longer used.
Replace it with galaxy/util.h, or better yet, just use galaxy/galaxy_all.h
and remove the headers galaxy.h, galaxy_io.h and serverstub.h.
- Incompatible change: the second argument of dispatch functions
is now reliably a GalSS_Environment * object. See the documentation
on adding a
server, as well as the upgrade guide on accessing
the Hub from dispatch functions and setting
up broker callbacks. Note: this change has analogous effects on
the Python,
Java
and Common
Lisp bindings.
- Incompatible change: the reinitialize message
no longer behaves idiosyncratically with respect to sending new messages.
See the upgrade
guide. Note: this change has analogous effects on the Python,
Java
and Common
Lisp bindings.
- Incompatible change: because administrative information is
now cached by the server bindings, it is no longer possible to send a new
message to the Hub by returning a frame from a dispatch function which has
the administrative information deleted. Use GalSS_EnvWriteFrame
instead.
- Incompatible change: the old method of declaring server and
dialogue function information, which was deprecated in 1.3, is now no longer
supported. See the upgrade
guide.
- Incompatible change and deprecation: the function GalSS_GetServerName
has been changed (and deprecated). It is now restricted for use with server
objects, not with connections. This is to support backward compability for
its use, which was almost exclusively in the server startup phase. Use GalIO_GetServerName
and GalIO_GetCommServerName
instead.
- Deprecation: in the context of standardizing the names for
printing, the functions sls_pp_frame, sls_cpp_frame, sls_pp_object, sls_cpp_object,
and sls_pr_object have been deprecated in favor of GalUtil_PPFrame, GalUtil_CPPFrame, GalUtil_PPObject, GalUtil_CPPObject, and
GalUtil_PrObject.
- Deprecation: The following functions have been deprecated because
dispatch functions are now reliably passed connection arguments. See the
upgrade
guide. These functions will be removed in a future release.
"(How to...) Use the
frame library"
"(How to...) Use the
timed task loop"
- The timed task loop now supports thread-based connection management.
- The timed task loop now fully exploits an optimization based on select()
which MIT had implemented but not used aggressively, with the result that
server message handling is significantly faster.
"(How to...) Use MIT logging"
- It is now possible to log program invocations and returns using LOG_IN:
and/or LOG_OUT: at the program level.
- In scriptless mode, it is possible to log when the Hub receives a
message and returns a reply using the MESSAGE: declaration together with
the LOG_IN: and/or LOG_OUT: declarations.
- It is now possible to invoke the logger directly from a server using
the log_keys builtin function.
The operation must be declared in your program file.
- It is now possible to timestamp program invocations and scriptless
message arrivals using the TIMESTAMP: declaration.
- It is now possible to log Hub events like alarm expiration, server
access errors, etc., using the LOG_HUB_ACTIVITY: declaration.
- It is now possible to log an arbitrary string to track versions of
your logfiles using the LOG_VERSION: declaration.
- Deprecation: the (:timestamp <key>) entry for LOG_IN:
and LOG_OUT: has been deprecated, because all keys will be logged with an
operation.
- Incompatible change: the deprecated keys LOG_FIRST:, LOG_LAST:
and LOG_ALL: have been removed.
- Incompatible change: the format of the MIT logfiles has been
modified.
- Format version number and optional user version number have been added.
- No keys are logged without a timestamped operation.
- The operations now contain the message type and the token
index.
- The form of the data has been rationalized to conform with the format
of data inside frames. In particular, strings now are delimited by double
quotes.
"(How to...)
Set up a brokered audio connection"
- Incompatible change: if you refer to your connection in your
broker callbacks, you'll probably have to make a small change due to the
change in the type of the second argument of dispatch functions. See the
section on setting
up broker callbacks in the upgrade guide.
- Deprecation: the reserved keys required for brokering can now
be set and accessed using the functions GalIO_FrameGetBrokerPort and GalIO_FrameSetBrokerCallID.
Users are encouraged to modify their code. See the upgrade guide.
"(How
to...) Understand the structure of a server"
- Incompatible change: the underlying structure of the toplevel
loop has been revised extensively to accommodate multiple connection servers.
If you have written servers with their own main loops, see the upgrade guide.
"(How to...) Use
a different main loop"
- Incompatible change: due to the requirements of multiple connection
servers, the behavior of the functions GalIO_ServerInit,
GalIO_ServerHandler,
and GalIO_ConnectionPoll
have changed in subtle and important ways. If you have written servers which
have their own main loop,
you should consult the upgrade guide. Note
also that the function GalIO_ConnectionPoll is now restricted to contexts
in which the timed task loop is not used, since it no longer resets its own
timed task. This is an internal change which should not be visible to any
users.
- Incompatible change: the behavior of Hub disconnects has changed.
Previously, if a server set a function to run when the Hub disconnected,
the server data would be passed to the function. For complex reasons, it
must be the connection object which is passed in the current release. This
affects a single MIT server, and we doubt it affects anyone else. The functions
have changed their signatures to reflect the fact that a GalIO_CommStruct
* is the argument of the disconnect function: GalIO_SetServerDisconnectCallback,
GalIO_SetDisconnectCallback,
GalIO_ReconnectInit, GalIO_ServerReconnect, GalSS_SetHubDisconnect, GalSS_HubReconnectInit.
"(How to...) Use non-MIT
Makefiles"
- Incompatible change: because the Communicator support code has
been aggregated into a single library and include directory, the include
and link directives have changed slightly.
"(How
to...) Use the command-line argument parsing and printing facilities"
- Incompatible change: as noted in the release notes for adding a server, these utilities
have been newly introduced into the Communicator library from the MIT sls_util
library. Their names have been changed in order to avoid symbol clashes.
"(How to...) Do signal
handling"
- Incompatible change: due to the requirements of signal handling
in threads, Communicator now has a special signal handler installation function.
It is strongly recommended that you use this function to install signal handlers.
"(How
to...) Connect multiple users using dispatch servers"
- MITRE has finally documented this facility.
"Reserved frame
keys in Galaxy Communicator"
- MITRE has introduced #defines for the C versions of these keys, and
documented the list of keys.
"Basic server example: double"
- The double example now halts when it reaches the largest integer, thanks
to remote error reporting.
- The double example now demonstrates run-time validation of Hub scripts,
scriptless interaction, and logging.
"MITRE utilities"
- A bug has been fixed in the MITRE stdin utility which caused it to
fail when the Hub halted and reconnected.
- Incompatible change: MITRE's dispatch function utility has
been incorporated into the core distribution. The functions MGal_CreateServerInfo(),
MGal_AddDispatchFunction(), MGal_InitializeServerDefaults() have been removed.
- Incompatible change: MITRE's multiple connection server utility
has been incorporated into the core distribution. The functions MGal_PollMultiConnServer(),
MGal_CreateMultiConnServer(), MGal_SetCommWrapperData(), MGal_GetCommWrapperData(),
MGal_GetCommWrapperComm(), MGal_GetMultiConnServerData() have been removed.
- Incompatible change: the way the stdin utility
is used has changed fairly substantially, since it used to store its information
in the server/connection but now needs to store its information as connection-specific
data. See the upgrade
guide.
- Incompatible change: the utility which implements the Hub as
an output device has been temporarily removed, because it is not thread-safe
and did not interact appropriately with multiple connection servers. The
supporting example has been removed as well.
- Incompatible change: MITRE's hub stream utility, which compensated
for the unusual behavior of the reinitialize dispatch function, has been
incorporated into the core distribution. The functions MGalIO_CreateHubStream,
MGal_HSSendFrame, MGal_HSSendMessage, MGal_HSReturnFrame, and MGal_HSReturn
have been removed. The supporting example has been removed.
"Tools
for constructing dispatch servers and UIs"
- MITRE has documented and enhanced the dispatch server protocol and
provided library facilities for constructing for using it. MITRE has also
provided a general-purpose dispatch server proxy for use with dispatch server
UI elements, and enhanced its UI server with dispatch protocol capabilities.
"MITRE tools"
- The MITRE process
monitor now provides a typein window which allows one to edit the command
line before restarting.
- An extremely evil bug in the process monitor has now been fixed in
which the CPU consumption of an idle Hub slowly climbed to almost 100% of
the CPU.
- The MITRE run_server
script now takes a -verbosity argument.
- MITRE now provides a utility
which translates MIT logs into XML.
Other
Unless you've been seriously messing with the guts of the Communicator library,
none of these changes should be visible to you.
- The function Gal_CopyHash
has been added.
- The syntax <server>.<opname> as the name of a
new message is now recognized by the Hub in the same way it is recognized
in MIT scripting. When MIT scripting claims the message, the server dimension
is ignored; in the scriptless case, it is taken as a directive to forward
the message to the specified server.
- The bug in Allegro 5.0 having to do with brokering in the Allegro
bindings seems not to arise in Solaris 2.7.
- The (undocumented) HUB_stub Python class in tools/lib/python has been
moved into GalaxyIO.py and renamed ClientConnection.
- Internal deprecation: the function GalSS_ForceReturn has been
simultaneously introduced and deprecated. Use GalSS_EnvForceReturn instead.
- Internal deprecation: the following functions have been deprecated
because dispatch functions are now reliably passed connection arguments.
See the upgrade
guide.These functions will be removed in a future release.
- Incompatible internal change: the (apparently unused) function
Gal_GetServerPort has been removed. It has been replaced by GalIO_GetServerDefaultPort,
which requires a server object argument.
- Incompatible internal change: the function Gal_GetServerName
is now deprecated, and its use has been restricted to contexts in which the
programmer has called Gal_SetServerName directly. In the vast majority of
circumstances, it will no longer work. Use GalIO_GetServerName
instead.
- Incompatible internal change: the following internal functions
have been removed.
- Incompatible internal change: the arglists of the internal
functions Gal_ReadObject, Gal_ReadFrame, Gal_ReadString, Gal_ReadList, Gal_ReadBinary,
Gal_ReadObjectLine, Gal_ObjectString,
Gal_FileNextLine,
Gal_FileCurrentLine,
and Gal_ReadToken
have all changed due to improved encapsulation of input streams.
- Incompatible internal change: the function Gal_CallServerFunction
has been replaced by GalSS_CallServerFunction.,
due to a change in the API.
- Incompatible internal change: the function Gal_GetProgramTagHash()
now returns a copy of the hash table it's passed, for thread safety reasons.
- Incompatible internal change: the name of the operation to
be invoked in the server is now the name of the frame, instead of the contents
of the op_name slot. Also, the name of the frame intended to invoke
the reinitialize message has been changed from welcome to reinitialize.
Finally, there is a special key for script-control-specific information called
:hub_program_info which takes the place of :ridx. All
of these changes are intended to support the consistency of incoming and
outgoing messages, and to make scriptless message invocation as transparent
as possible in the Hub.
- Incompatible internal change: the communications protocol has
been extended slightly to allow encoding of various metalevel message types:
new message, reply, error, etc. If you've written native programming language
bindings for Communicator, you'll want to pay attention to this.
- Incompatible internal change: the communications protocol change
now subsumes the "bounce" message which was used to reject connections above
the maximum number permitted. If you've written native programming language
bindings for Communicator, you'll want to pay attention to this.
Known bugs in 2.0
- The Java bindings sometimes truncate audio when interacting with the
audio device. We doubt that people are planning on writing a Java audio server,
so we're not in a terrible hurry to track this one down.
- The MIT audio server sometimes exhibits repeated clicking on short
outputs using the OSS sound drivers on Linux or X86 Solaris. We don't know
whether this is a problem with the MIT audio server or with the OSS drivers.
There are also some odd cases if you leave the audio server running when
you shut down and restart the Hub where the audio server will not flush its
output buffer.
- There is a bug in logging for error replies. If there are no LOG_OUT:
keys specified in RULE:, PROGRAM: or MESSAGE: for an incoming reply from
a server or a server-to-server subdialogue, error replies will not be logged
unless you put "system_error" in your TIMESTAMP: list. This bug will be fixed
in a later release.
- Because of the way the Java bindings map dispatch function names to
method names, the Java servers will not generate correct default message
signatures to report back to the Hub, and the -validate flag may erroneously
report that the server isn't aware of a particular message. If you want signatures
reported correctly, do not rely on the automatic generation of default signatures.
- The Allegro bindings still "hang on" to server ports for a while if
the server dies inelegantly. We know that this has to do with REUSEADDR in
Allegro, but we haven't upgraded to the new socket library in 5.0 which makes
it easy to fix this problem.
- It's not a particularly good idea to try to compile multiple platforms
simultaneously in the same distribution. In particular, clean_headers.pl
must refer directly to your Perl executable, which may be in different places
on different platforms. There are other clashes that might arise as well.
Significant omissions
There are a number of things which we had hoped to get to but didn't, which
render the distribution somewhat inconsistent.
- Although we are fairly certain that the core Communicator library is
thread-safe, it will not work without modifications on Windows NT, at least
at the moment. There is a Cygnus-supplied DLL
which one can obtain which provides a POSIX threads wrapper around the Windows
native threading, but we haven't had a chance to download and test it; furthermore,
as of October 1999 there were a couple functions we use (such as sigwait())
which they've documented as not working yet.
- Although we have invested a great deal of effort into segmenting the
Communicator Hub and MIT Hub scripting, we haven't had a chance to try writing
our own scripting module, nor have we documented the API for those who wish
to try writing their own scripting module. Our best advice is to examine
the MIT scripting module in contrib/MIT/galaxy/src/libGalaxyHubControl.
- Although we made signfiicant progress in segmenting the Communicator
Hub and MIT Hub scripting, the job isn't quite finished. The builtin server,
in particular, most likely still has MIT-specific functionality in it.
- Although we've finally provided documentation for dispatch functions,
we still haven't documented the MIT gui server, nor have we provided well-supported
scripts for setting it up (it's not at all obvious).
- We have still not had the chance to upgrade our documentation on how
to build an end-to-end system.
Last modified September 28, 2001