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. For the current distribution, you can find a list
of new features here. You can find a detailed
description of the steps required or recommend to upgrade existing features
of Galaxy Communicator here.
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.
Please send comments and suggestions to:
bugs-darpacomm@linus.mitre.org
Last modified September 28, 2001
Copyright (c) 1998, 1999, 2000, 2001
The MITRE
Corporation
ALL RIGHTS RESERVED