Galaxy Communicator Documentation:
Release Notes
This document briefly lists all the changes from one Galaxy Communicator
distribution to the next for the current major version of Galaxy
Communicator. You can find a list of new features here. You can find a detailed description
of the steps required or recommended to upgrade existing features
of Galaxy Communicator here.
You can also inspect release notes for previous major version.
September 2002: Version 4.0
Core distribution
- Enhancement. Added support for references
to specific servers via provider
names.
- Enhancement. The Hub GUI message set is
now complete and documented.
- Enhancement. Introduced broker proxies.
- Enhancement. The infrastructure now supports
timestamps.
- Enhancement. Added the functions Gal_ArrayObjectExpandable,
Gal_ListObjectExpandable.
- Enhancement. The verbosity levels are now rationalized,
and the print utilities now allow you to change the print behavior.
- Enhancement. The function GalSS_StartAndRunServer
now returns a flag indicating whether server startup was successful
or not.
- Enhancement. The documentation now elaborates
in a little more detail about reference
counting and environments.
- Enhancement. We've expanded the mechanisms
for substituting variables into objects. Gal_VAReadVarFrameFromString
now works recursively and in lists, and we've added Gal_VAReadVarObjectFromString
and the $bind entity
reference function.
- Enhancement. The internal frame and object
printing code has been reorganized to cover truncated printing of complex
elements (previously handled separately).
- Enhancement. Added the Builtin server functions
hub_ping, hub_token_timestamp,
hub_gc_version,
hub_sleep.
- Enhancement. Simplified and rendered consistent
the core library's use of internal memory stores to manage frames,
objecs and other elements.
- Enhancement. Server locations are much
more powerful in 4.0; it is now possible to switch the direction
of connectivity, use provider
names, and also to reference entries on the server side which don't
correspond to the server's name.
- Enhancement. In order to support the more restrictive
C++ type enforcement, we've added const to every char
* function parameter in the C library headers which is guaranteed
not to alter the string which is passed in. In the future, we may attempt
to do this for other types.
- Enhancement. Following up on MIT's removal of
the last dependency on dispatch functions without environment
arguments, we have removed any reference to #define USE_SERVER_DATA
in the servers. This #define is now a no-op, and the
behavior it induced in previous releases is now the only possible
behavior.
- Enhancement. We've expanded the server-side
API for listener-in-Hub support.
- Enhancement. We've added navigation bars to the HTML
documentation.
- Enhancement. The entire distribution now works on Windows,
including the tutorial.
- Enhancement and bug fix. We have reorganized
the way the Hub processes outbound messages. Previously, it had
dispatched the messages immediately, or inserted them into a session-specific
queue. This behavior was causing a number of inconsistencies, degrees
of awkwardness, and bugs in the way service providers were selected.
In 4.0, outbound messages are inserted into a common global queue,
and are considered for dispatch in the order in which they are queued.
- Enhancement and bug fix. In previous releases, it was
not possible to create brokers without starting them. This was a significant
problem in threaded servers, where the broker thread might start up (and
perhaps finish) before various modifications and enhancements were made
to the broker, such as setting up abort callbacks. In version 4.0, it
is now possible to create a broker without starting it. See the broker
documentation and the thread
notes.
- Bug fix. Fixed a bug where postponements weren't
clearing all the flags they needed to clear in the Hub.
- Bug fix. Fixed a bug where remote errors generated
in scriptless mode weren't being returned to their callers appropriately.
- Bug fix. Thanks to Peter Gober, discovered and
fixed a wide range of cases where the core library was not truly thread-safe,
in particular ensuring that mutexes would not be stranded by a wide
range of previously ignored thread cancellation points. Also, there were
problems synchronizing reply messages because the inbound connection
queue was being unlocked and re-locked instead of being locked throughout.
- Bug fix. A bug where internal queues of objects
were failing on reentrant calls has been fixed.
- Bug fix. In the process of reorganizing the
internal processing of outbound messages, we fixed a Hub bug where
recursive calls to Builtin.call_program
were causing a tight loop which excluded all other Hub message processing.
- Bug fix. Under some circumstances, the Hub's
initial token was not responding to logging directives appropriately.
This has been fixed.
- Bug fix. Performed considerable analysis of
memory usage in the server library and the Hub, and fixed a number
of latent leaks which were previously difficult to find because the
core library manages the creation and destruction of frames, objects
and other elements from a preallocated store.
- Bug fix. Fixed a bug in the Hub where service providers
which contacted the Hub and disconnected before receiving the results
of processing tokens it originated would cause a seg fault when the Hub
attempted to return the results.
- Incompatible change. As part of the cleanup
of verbosity levels, the semantics of the values used in the core library
code has been revised. Previously, constants like GAL_PINFO1_LEVEL
were interpreted not as corresponding to values for GAL_VERBOSE,
but as the value which GAL_VERBOSE had to exceed in order
to trigger printing. This was confusing to the programmer.
- Incompatible change. In version 3.3, undefined
dispatch functions caused the server to raise an error back to the
Hub, but didn't cause the Hub to raise an error back to the caller;
rather, a new error token was generated, and no information was filtered
back to the token which caused the error. In 4.0, the Hub raises an error
in addition to creating the new error token.
- Incompatible change. The memory management
conventions for Gal_VAReadVarFrameFromString
have changed.
- Incompatible change. As a result of imposing
better memory management on Hub programs, the function signatures
for the undocumented functions Gal_GetProgramEntity
and Gal_SetProgramEntityLocation
have been changed.
- Incompatible change. The undocumented
functions GalIO_HubHandler, GalIO_GetCommFrame and Gal_SplitServerName
have been removed.
- Incompatible change. The function signatures
of the undocumented functions Gal_NewTest and Gal_CreateProgramEntity
have been changed as a result of a massive internal reorganization
of program file parsing.
- Incompatible change. The function signature
of the undocumented function GalIO_ClientInit
has been changed as a result of simplifying the internals of connection
management.
- Incompatible change. The format of the
-gui Hub command line
argument, new in 3.3, has been changed.
- Incompatible change. The Builtin server dispatch
function hub_continue
no longer permits location strings in its :service_provider
argument key, but now supports the new provider
names.
- Incompatible change. Since MIT has removed its
last dependencies on global variables for environments, the undocumented
functions GalSS_DispatchViaHub and GalSS_WriteFrameToHub have been
removed, as well as support for the hidden global environment variable.
- Incompatible change. Following up on MIT's removal
of the last dependency on dispatch functions without environment
arguments, we have also removed all support for such dispatch
functions. The function GalSS_AddBareDispatchFunction has been
removed, and the signature of the functions Gal_AddDispatchFunctionEntry,
GalIO_AddServerDispatchFunctionEntry
and GalIO_AddCommDispatchFunctionEntry
have been modified.
- Incompatible change. In order to distinguish between
broker creation and broker startup, we have had to redefine the semantics
of the broker events GAL_CONNECTION_BROKER_OUT_STARTUP_EVENT
and GAL_CONNECTION_BROKER_IN_STARTUP_EVENT. See the upgrade notes.
- Incompatible change. The rules for matching server location
file overrides to Hub declarations have changed. See the upgrade notes.
MIT contributions
- Enhancement. We've reorganized the Hub
program file parsing code to make it easier to maintain. One dimension
of this modification was to eliminate separate data structures for
parsing the program file and for using the information in the running
Hub.
- Enhancement. As part of adding provider
names, we've expanded the range of locations which allow service
type and provider name references. The enhanced Hub program directives
are SERVER:, SERVERS:, IGNORE:, TIMESTAMP:, and MESSAGE:.
- Enhancement. Added support under the hood
for complex entity references, which are currently manifested in
the new $id and $bind entity reference function.
This functionality will allow us to add a much larger range of extensions
in the future quite easily.
- Clarification and bug fix. In previous
releases, the applicability and scope of the program-
and message-level logging was not well specified, and somewhat
sloppy. For instance, values of the TIMESTAMP: directive which
were qualified with a service
type prefix were having their prefix stripped before processing,
resulting in erroneous timestamps for server2.op when
server1.op was requested. We have now cleaned up this
problem and others, and clearly specified the rules under which
timestamping and logging will occur at the program and message level.
- Bug fix. Fixed a bug in the undocumented
verify_dctl_file utility which had rendered it unusable for at least
two releases.
- Bug fix. In version 3.3, the ERROR: Hub program directive
would be ignored if it had no argument, which is a legal use. This
bug has been fixed.
- Bug fix. In version 3.3, the code which
prints out Hub programs had failed to keep up with new Hub program
directives. All Hub program directives are now printed correctly.
- Bug fix. Fixed a bug where values of the
CONDITIONS: Hub
directive were not being read using the correct tokenizer.
- Bug fix. In previous versions, there was
a bug in parsing complex Hub rule conditions which was leading to
an erroneous report of incorrect syntax. This bug has been fixed.
- Bug fix. MIT discovered and fixed a small bug
where messages dispatched from a rule with the CONTROL: :asynchronous
directive were not recognized as not expecting a result.
- Incompatible change. MIT has updated its turn management code to pass
environments as parameters, rather than relying on a hidden global
variable. This has resulted in a number of changes:
MITRE contributions
- Enhancement. We have added support for
broker proxies in the Java bindings. See the Java
bindings documentation for details.
- Enhancement. The stdin polling
utility now works on Windows.
- Enhancement. The Java bindings have been
updated to support the same diagnostic verbosity levels as the other
language bindings.
- Enhancement. The process monitor configuration files now
recognize the INCLUDE: directive, and always recognize the expansion
of $ARCHOS.
- Enhancement. Several new classes have
been added to the Java bindings:
- Enhancement. The Java DataOutBroker
has been updated to support two callback methods: disconnectReceived
is called when the broker is told to disconnect from its clients
(once it times out) and connectionEstablished
is called when the broker receives a new client connection. These
methods can be overridden by subclasses to provide the desired
behavior.
- Enhancement. It is no longer necessary
to implement all "received" methods on the interface of the Java
DataInBroker.
You only need to implement the methods that you need.
- Enhancement. The Java method getNameForObject
has been added to GalaxyObject.
- Enhancement. A variety of new Java logAndSendErrorMessage
methods have been added to Server.
- Enhancement. New append methods have been
added to the Java array objects to allow array objects of the same
type to be combined (e.g., see Int16.append).
- Enhancement. New "get" methods have been
added to GFrame
to support reading numerical array objects from frames.
- Enhancement. Support for accessing token
timestamps via the Java bindings has been added. See Environment.getTokenTimestamp
and Environment.inheritTokenTimestamp.
- Enhancement. Support for accessing and
using service provider IDs via the Java bindings has been added. See
Environment.getOriginatingProvider,
Environment.dispatchFrameToProvider,
Environment.writeFrameToProvider
and Environment.dispatchFrameToProviderWithContinuation.
- Enhancement. The rules that dictate how
listener ports are selected in Java servers have been clarified.
In particular, if either the -assert or -port
command line arguments are passed to a server or the server's port
number is set via the -server_locations_file command line argument,
MainServer.setPort(int)
cannot be used to change the port. In addition, new constructors
have been added to MainServer
that take a port number as an initialization argument. This allows
the default port to be overridden before the command line arguments
are processed (e.g., before -assert is processed and locks
the server into using the default port).
- Enhancement. We now provide Microsoft
Visual Studio project files for building the Python bindings.
- Bug fix. Fixed a tiny bug in the process monitor
where receiving the EAGAIN error on read was causing it to believe
that the process it was controlling was dead.
- Bug fix. Fixed a small bug in the log analysis code which
arose due to stricter interpretation of tuple arguments in versions of Python
after 2.0.
- Deprecation. The following methods are
deprecated in the Java bindings as of 4.0:
- galaxy.server.DataInBroker
- DataInBroker(Server,
InetAddress, int, GFrame) (use DataInBroker(Server,
InetAddress, int, String) instead)
DataInBroker(Server,
String, int, GFrame) (use DataInBroker(Server,
String, int, String) instead)
- galaxy.server.MainServer
- galaxy.server.Server
- Incompatible change. The Java DataInBroker
constructors now throw IOException.
- Incompatible change. The Java galaxy.lang.BinaryObject
class has been removed (it had been deprecated since 3.0). The various
Galaxy Communicator array objects are now implemented as ArrayObjects
in the Java bindings. Related to this, the deprecated byte[]-based
constructors for the numerical array objects have been removed,
as has the GalaxyOutputStream
write(BinaryObject, int) method.
- Incompatible change. The Java bindings
now encode/decode XDR strings using the ISO-8859-1 encoding. Previously,
UTF-8 was used, but this is not compatible with the encoding/decoding
support used by the other language bindings.
- Incompatible change. All Java code that
was deprecated in Galaxy Communicator 3.0 has been removed. This
includes:
- Incompatible change. The audio brokering example
has been modified and generalized, and some of the servers have been
removed.
- Incompatible change. An additional argument has been added
to the constructor for the Server class in the Python bindings, immediately
after the server_locations_file argument. See the upgrade
notes.
Known bugs
- In some circumstances, the Hub will queue messages
for which there is no eligible provider; in other cases, it won't.
This inconsistency will be fixed in a subsequent release, and the
programmer will be allowed to specify a timeout for queueing.
- We know of a threading bug involving outgoing
brokers with multiple connections. This bug is intermittent, and the
user who reported it cannot reproduce it in such a way that we can
figure out what's going on yet.
- On Windows, a call to connect() to establish a socket connection takes
a considerable amount of time to fail when there's no listener. This is an
issue with the Windows implementation of connect() which we can't control.
- The -assert server command line argument still permits the
user to call GalIO_SetDefaultServerPort.
- In some cases in program files (i.e., in the middle of an object rather
than between objects), escaped line breaks don't work.
Last modified August 9, 2002
