Galaxy Communicator Documentation:
Release Notes for Version 3.x
This document briefly lists all the changes from one Galaxy Communicator
distribution to the next for versions 3.x.
Version 3.x is not the current version of Galaxy Communicator.
January 2002: Version 3.3
Core distribution
- Enhancement. The distribution can now be configured for compilation using GNU configure
exclusively, although the old method still works. All references to specific
platform dependencies are now in include/galaxy/sysdep.h, and
many files and headers throughout the distribution have been modified. Old
cruft relating to platforms we no longer have access to for testing (e.g.,
DEC Alpha OSF/1 and HP/UX) has been removed.
- Enhancement. As a byproduct of the new configuration process,
we can easily test and compile on three additional platforms: SGI IRIX, Intel
FreeBSD, and MacOS X/Darwin.
- Enhancement. New Builtin server functions hub_set_verbosity,
hub_raise_error.
- Enhancement. A couple of unnecessary bottlenecks in the
transport layer have been removed, resulting in significantly higher message
throughput.
- Enhancement. We have confirmed that we can cross-compile
the Galaxy Communicator infrastructure for Linux on the iPaq.
- Enhancement. We have released experimental support for external
Hub visualization servers. These servers can subscribe to special message
streams which indicate the status of the Hub. See the -gui command line flag
for the Hub executable.
- Enhancement. New Hub command line flag -suppress_pacifier.
- Clarification. We've clarified the precedence when inconsistent
listen
status flags are set.
- Clarification. We've clarified in the non-MIT makefile documentation
that the Communicator libraries should follow the source or object files
in your link line.
- Clarification. We've clarified that the use of #ifndef
to ensure that header files are only loaded once is counterproductive in
the case of server declaration files.
- Bug fix. To support BSD operating systems, we identified
and fixed a bug where BSD platforms couldn't determine their own IP address
using the existing code.
- Bug fix. We finally changed the name of a file in the templates
subdirectory whose name differed from another file only by capitalization.
- Bug fix. A bug in the Hub was identified and fixed where
sessions could have been freed prematurely if multiple servers were locked
to it.
- Bug fix. A bug in the Hub was identified and fixed where
server messages were sometimes not being freed, and one case where the server
messages were potentially referenced after they were freed.
- Bug fix. A bug in the Hub was identified and fixed where
messages queued for a server in the Hub were not all getting sent if some
of them didn't require a reply.
- Bug fix. A bug in the Hub was identified and fixed where
round-trip messages from a server which were processed in scriptless mode
by the Hub were never returning when the destination server did not provide
a reply.
- Bug fix. A bug in the core C library was identified and
fixed where threaded servers could potentially fail to free a mutex if the
server was contacting the Hub.
- Incompatible change. As a consequence of the new configuration process, the experimental
cross-compilation support
has been completely changed.
MIT contributions
- Enhancement. We have added the capability in the Hub scripting
language of monitoring a server for a new message and interpreting it as
a reply. We call this capability Hub
continuations. It is available as scripting language directives
and as a Builtin function.
- Bug fix. Fixed a bug where the Builtin function wasn't being
declared if there were no programs or messages.
MITRE contributions
- Enhancement. It is now possible to compile and use the Python
process monitor without compiling the Python bindings.
- Enhancement. The Java bindings now support the same Hub
connection policy flags as the other language bindings.
- Enhancement. The cleanup
method has been added to the MainServer
class, allowing subclasses to run arbitrary code before the server shuts
down.
- Enhancement. The process
monitor now makes arguments passed to its configuration files available
by name as well as position.
- Bug fix. While we are no longer officially maintaining the
XML log manipulation code, we have addressed a bug where partial match information
in the XML annotation rule matcher was being preserved by accident. We do
not have a test suite for this section of code, so we can't be absolutely
sure that we haven't broken something else, but the fix is very local and
we can't imagine what other effects it might have beyond addressing this
bug.
- Bug fix. When a Java server that is acting only as a Hub
client starts an outgoing broker, the listener thread that is started as
a result no longer accepts regular connections from the Hub.
- Incompatible change. In MainServer,
a number of methods have been renamed: setActsAsClient is now setActsAsHubClient,
isClient is now isHubClient,
setActsAsListener is now setActsAsHubListener,
isListener is now isHubListener,
startListenerThread is now startHubListenerThread (and it was changed from
protected to private), and startClientThread is now startHubClientThread
(and it was also changed from protected to private). Finally, the MainServer
connection bitmask flag values (GAL_CONNECTION_LISTENER,
GAL_BROKER_LISTENER,
GAL_HUB_CLIENT,
GAL_SERVER_TYPE_MASK)
have been made protected (were public).
- Incompatible change. In order to establish the Open Source
toolkit, all servers previously in contrib/MITRE, along with their
documentation and supporting examples, have been removed from the distribution.
Known bugs
Two known bugs from 3.2 remain:
- In rare cases, if two broker servers attempt to contact each other
simultaneously, a deadlock will arise. This bug is fixable, but would require
some serious internal reorganization. (Observed 3/01)
- Line breaks inside Galaxy Communicator list objects in program
files do not work. (Observed 2/01)
We judge that fixing these two bugs is not a high priority at the moment.
All bugs which have been reported since the release of 3.1 have been fixed.
October 2001: Version 3.2
Core distribution
- Enhancement. The documentation
has been completely reorganized into four sections: tutorial, advanced topics,
reference and administrative information. The tutorial material is mostly
new, and represents a completely updated version of the original Communicator
training course (previously distributed separately). This tutorial is designed
to be self-guided, and is generously illustrated.
- Enhancement. The flags
which control server behavior when they contact the Hub didn't have
a value which allowed the user to specify that the server should shut down
if it couldn't contact the Hub in the first place. In addition, there were
some intuitively mnemonic names and values (for masks, for instance) which
were missing. These problems have been remedied (not in Java yet).
- Enhancement. For advanced programmers, there is now an undocumented
capability of overriding the default method for selecting dispatch functions.
We use this to allow the Python bindings to use native dictionary lookup
as its selection method, which also allows us to defeat the selection method
entirely for the new Python-based unit tester.
- Enhancement. For 3.2, we will be using a different, better
tool to generate the PDF version of the documentation. Due to expanded documentation
and illustrations, this document has grown to 10MB, and will be distributed
separately.
- Enhancement. Added the functions GalSS_EnvReturnRequired
and GalUtil_SetVerbose.
- Bug fix. In 3.1, service providers in the Hub which were
providers for multiple service types were being added multiple times to the
global list of service providers, leading to a segmentation fault when the
provider disconnected. This has been fixed.
- Bug fix. In 3.1, session locks
were being misinterpreted by the Hub; restrictions on message received were
being interpreted as restrictions on messages sent, and vice versa. This
has been fixed.
- Bug fix. Because of a flaw in the Makefile templates, it
was not possible to maintain simultaneously different settings for whether
to compile shared libraries on different platforms. This bug has been fixed.
- Bug fix. MIT discovered and helped fix a bug where under
unusual circumstances involving queued brokers in C which were not activated,
the brokers would loop forever.
- Bug fix. MIT discovered and fixed a bug where read streams
associated with strings would rewind incorrectly under unusual circumstances.
- Bug fix. We have finally fixed a longstanding bug where
program files with Unix line terminations could not be read properly on
Windows.
- Bug fix. We have discovered and fixed an arcane Hub bug
where extraneous unexpected reply messages from asynchronous Hub calls could
destroy tokens by accident.
- Bug fix. With MIT's help, we have discovered and fixed a
bug where server and session lock release requests were not being transmitted
from server to Hub.
- Bug fix. We have fixed a bug where older servers which use
bare connections to write messages to the Hub couldn't control server and
session locking correctly.
- Incompatible change. The way service provider eligibility
in the Hub is determined has changed slightly. In particular, in 3.1, service
providers which are the only provider for a particular service type were
being used because they were the only available server, even when they were
locked to other sessions. Service providers which are locked to sessions can
now be used only by that session, without exception.
- Incompatible change. The signatures of the undocumented
functions Gal_FindDispatchFunctionEntry and Gal_EncodeDispatchFnSignatures
have changed.
- Incompatible change. The function Gal_GetListValue has
been deprecated, and will be removed in the next major release.
MIT contributions
- Bug fix. In 3.1, any operations referenced in Hub program
rules which had no explicit service type (e.g., Parse instead of
Parser.Parse) were erroneously assigned a service type at Hub
startup time (in general, the last service type mentioned which supported
the operation). As a result, if multiple service types supported the same
operation, only one service type would ever be considered, even though the
script writer intended the reference to be ambiguous. This bug has been fixed,
along with a number of related bugs which had been hidden by this bug. However,
if only one service type supports a given operation, that service type is
still explicitly assigned at read time to operations without a service type.
- Enhancement. MIT has provided minor enhancements to its
dialogue tools.
MITRE contributions
- Enhancement. In support of the new tutorial, the toy travel demo
has been completely redesigned and reimplemented, so that the code as well
as the program file are pedagogically appropriate.
- Enhancement. The process
monitor now accepts a configuration file as an argument, as an alternative
to the sequence of flags it has previously accepted (and still accepts).
This functionality makes visible some process monitor extensions we had
previously only used internally in our test harness. This enhancement makes
it significantly easier to maintain and start up examples in the tutorial,
as well as making it simpler to port the process monitor to Windows.
- Enhancement. In support of the new tutorial, the unit tester
has been completely redesigned and reimplemented. It now allows you to connect
to a Hub pretending to be a server, or to a server pretending to be a Hub.
It also provides a graphical interface to allow you to respond to incoming
messages and to send new messages of your own, and keeps a mouseable history
of frames for you to select from if you choose.
- Enhancement. We have augmented the audio example
and brokering documentation with
examples of outbound streaming broker data.
- Bug fix. In the Python bindings, the equivalent of GalIO_ClientConnect
did not support disconnect callbacks appropriately. This has been fixed.
- Bug fix. In the Python bindings, it was not possible to
reset the verbosity level for the underlying C library after startup. This
has been fixed.
Known bugs
Two known bugs from 3.1 remain:
- In rare cases, if two broker servers attempt to contact each other
simultaneously, a deadlock will arise. This bug is fixable, but would require
some serious internal reorganization. (Observed 3/01)
- Line breaks inside Galaxy Communicator list objects in program
files do not work. (Observed 2/01)
We judge that fixing these two bugs is not a high priority at the moment.
All bugs which have been reported since the release of 3.1 have been fixed.
June 2001: Version 3.1
Core distribution
- Enhancement. Perl is no longer required by the Communicator
infrastructure.
- Enhancement. New API functions Gal_NumNonNullProperties,
Gal_PrintEntity
- Enhancement. The Makefile infrastructure now includes experimental Unix support for cross-compilation.
- Enhancement. The nightmarishly complex process of embedding
Communicator in external main loops has been vastly simplified.
- Enhancement. The Hub builtin server now has a number of
new functions: call_program,
which eliminates the idiosyncracies in invoking subprograms and supports
returns from subprograms; hub_available_servers,
which provides access to the list of service types that are currently enabled;
hub_token_owner,
which provides the service type of the originating server for the current
token; and hub_pause,
which introduces a pause after each Hub message dispatch for demo purposes.
- Incompatible change. The default verbosity level is now 3; it was
previously undefined, which was equivalent to 6 (the most verbose).
- Clarification. If you use Python, it must be configured
with Tkinter support.
- Clarification. The function Gal_NumProperties counts
properties with NULL values. Use the new Gal_NumNonNullProperties
to skip NULL-valued properties.
- Clarification. For reasons of backward compatibility, the
keys :pred and :PRED are special
to Gal_ReadFrameFromString and its relatives, and should be avoided
by sites other than MIT.
- Clarification. The 3.1 distribution also contains undocumented
experimental hooks for supporting an external Hub visualization tool. These
hooks are disabled because the functionality is only partially implemented.
- Bug fix. In 3.0, if a frame contained a key-value pair with
a NULL value, the property was counted but not encoded in the XDR transport,
causing the number of properties in the frame to be encoded incorrectly in
the XDR transport. This bug is now fixed.
- Bug fix. There is now a more reliable way of avoiding name
collisions with OS-level C library functions which only exist on a subset
of supported platforms.
- Bug fix. In 3.0, the automatically generated Makefile dependency
files incorrectly expanded the ARCHOS Makefile variable, partially invalidating
the dependencies on platforms other than the one they were generated on.
This bug has been fixed, along with a number of other lurking bugs in the
dependency generation.
- Bug fix. In 3.0, tokens were not consistently being returned
to their originating servers when they died, due to poor code organization.
This facility has been completely reorganized.
- Bug fix. In 3.0, a null OPERATIONS: directive in service
type declarations in the Hub program file could lead to apparently random
server choices for operations, including servers which did not support the
operation. This bug has been fixed.
- Bug fix. In 3.0, servers which were configured
to shut down after their connection to the Hub was lost were using
the wrong facility to shut down, with the result that the wrong thing was
happening in external main loops. This bug has been fixed.
- Bug fix. In 3.0, there were a couple cases where sessions
were not being created automatically in the Hub. This bug has been fixed.
- Bug fix. In 3.0, under some circumstances sessions could
be destroyed without their corresponding database history being freed, leading
to potential memory leaks. This bug has been fixed.
MIT contributions
- Enhancement. New Hub scripting IGNORE: directive, IN comparison,
- Enhancement. The Hub scripting global namespace is now
writable, and there is a new value for the MODE: directive called global_read_only
which will write-lock the namespace.
- Enhancement. The current logfile name is now available
as a session key in the Hub scripting.
- Bug fix. The DEL: Hub scripting directive seg faulted when
only simple keywords were listed.
MITRE contributions
- Enhancement. Running Python servers in debug mode no longer
causes an exit when an error is encountered, but rather prints out better
debugging information.
- Enhancement. The process
monitor now takes two new arguments: --master_title, to set
the title of the process monitor window, and --clear_history, to
automatically clear the history of each pane after a given number of lines
are printed.
- Enhancement. The following methods have been added to the
Java bindings:
- Enhancement. Added initial support for the -verbosity
command
line argument in the Java bindings.
- Clarification. We have determined that the Python bindings
work with Python 2.0.
- Incompatible change. The Java method MainServer.contactHub
has been modified. It no longer takes a Server
argument. Rather, if the Hub contact policy argument is set to -1, the
default policy of the invoked MainServer
is used.
- Bug fix. "make distclean" at the toplevel no longer operates
on contrib/MITRE twice.
- Bug fix. In 3.0, the Allegro and Python bindings were missing
the functionality provided by GalSS_EnvGetSessionID
and related functions. This has been fixed.
- Bug fix. In the Python Tk bindings, the application wasn't
exiting appropriately when the server exited. This is now fixed.
- Bug fix. The PostGres wrapper now handles SQL queries other
than insert and delete appropriately.
Known bugs
- In rare cases, if two broker servers attempt to contact each other
simultaneously, a deadlock will arise. This bug is fixable, but would require
some serious internal reorganization. (Observed 3/01)
- If you ask the Hub on NT to read a program file which was written
on Unix, the Hub will fail due to the difference in line breaks between platforms.
This bug has apparently been lurking for quite a while. (Observed 3/01)
- Line breaks inside Galaxy Communicator list objects in program
files do not work. (Observed 2/01)
- The tool which automatically generates the PDF documentation from
the HTML documentation does a good but not great job, and in some cases the
formatting is quite odd. (Observed 3/01)
January 2001: Version 3.0
Core distribution
- We have documented and radically improved session management support. This includes
a better defined use of call environments.
- We have introduced continuations
to allow better management of asynchronous communication with the Hub.
- We have introduced server
locations files to allow dynamic control of the location of Hub and
server listeners.
- We have documented the GC_VERSION
header definition, which allows you to conditionalize your servers
against different versions of the Galaxy Communicator distribution.
- The timed task facilities now allow you to register error streams
as well as input and output streams for monitoring, and also give you access
to the reasons the task is being run. See the functions Gal_AddTaskExtended
and Gal_TaskPkgRunReasons.
Due to this change, we now recommend that programmers upgrade from the
"simple" timed task API. See the upgrade
notes.
- The core frame library now includes support for dynamically expandable
lists and binary objects. See the functions Gal_CreateListObject
and Gal_CreateBinaryObject.
- The distribution now includes versions of object creation functions
which allow explicit control of memory management, as well as creation functions
for all the array types which could only be brokered in previous releases.
- As a side benefit of using the C library as the basis of the Python
and Allegro language bindings, the API for embedding Communicator servers
in other main loops has been tremendously improved. You are strongly encouraged
to take advantage of these modifications. See the upgrade
notes.
- Thread startup for timed tasks now works on Windows NT.
- The syntax of Hub scripts has been extended in a number of powerful
and consistent ways. It is now possible to refer to the memory states of
sessions, etc. in a transparent way. In addition, the Hub now organizes its
known servers into service types and service providers, which simplifies and
clarifies the process of selecting a server to deliver a message to. Finally,
the Builtin server no longer needs to be declared. See the extensively revised
scripting documentation for details.
- Both brokering and message traffic have been reimplemented using
the XDR data encoding. There is no longer any distinction between the frame
types which can be brokered and the frame types which can be included in
frames. In addition, brokering floats between platforms finally works. Also,
there is no longer any possibility of confusing values of the :pred
key with elements of the list of predicates in a frame.
- The reinitialize
dispatch function can now be called as a normal dispatch function.
- It is now possible to build frames from string representations
with embedded variables. See the function Gal_VAReadVarFrameFromString.
- The Hub now informs the server whether it needs a reply or not,
and the server bindings now return a pacifier reply when the dispatch function
doesn't return a frame. This means the Hub will never block waiting on a
reply from a server.
- Servers now provide a unique index for each server-to-server request
via GalSS_EnvDispatchFrame,
and appropriately postpone new requests while they're waiting for a response.
This more robust behavior is superfluous under normal circumstances, but
is crucial for proper functioning when two threads are using the same connection.
- A bug in internal socket management in 2.1 has been fixed, in which
mutex protection for sockets was not fine-grained enough. This caused multiple-connection
servers to deadlock in threaded mode in 2.1.
- Naming conventions for non-public functions in the core library
have been cleaned up and simplified.
- We have clarified in the documentation that incoming broker
callbacks have responsibility for freeing the data they're passed. See
the upgrade
notes.
- We have cleaned up the event-driven programming and callback data
storage models for servers, connections and brokers considerably. Some of
this cleanup has resulted in recommended upgrades for incoming brokering.
See the upgrade
notes and the new section on event-driven
programming.
- We've done some internal cleanup and reorganization of the headers.
This should be transparent to the programmer.
- The distribution now includes a PDF version of the documentation.
- Gal_ObjectEqual,Gal_MatchFrame and Gal_ObjectCaseEqual
now work on list objects.
- A long-standing bug where error keys were not reliably logged in
the Hub has been fixed.
- Deprecation. It's become clear that we can't keep changing
the signature of GalSS_InitializeServerToplevel
every time we add a new command line argument to the server bindings. The
following functions have been deprecated.
- Deprecation. The frame key :hub_new_session in
new messages currently forces the Builtin server function new_session to be called.
This mechanism will be replaced in a subsequent release. The frame key :session_id
can currently be used to access and modify the session associated with
a message. This behavior is now deprecated; use GalSS_EnvGetSessionID
and GalSS_EnvUpdateSessionID
instead.
- Incompatible change. As part of cleaning up the callback
data storage model, the signature of GalIO_SetServerData
has changed.
- Incompatible change. Dispatch server support has been removed
from the distribution.
- Incompatible change. The following deprecated functions
have been removed:
- sls_pp_frame
- Gal_GetValue
- sls_cpp_frame
- sls_pp_object
- sls_pr_object
- sls_cpp_object
- Gal_UnwrapValue
- Gal_Value
- Gal_ValueWarn
- Gal_ValueWarnWithKey
- Gal_ValueSilent
- GalIO_SetServerDisconnectCallback
- GalIO_ReconnectInit
- GalIO_ServerReconnect
- GalSS_SetHubDisconnect
- GalSS_GetServerData
- GalSS_GetServerName
- GalSS_GetServerSock
- GalSS_CloseServerSock
- GalSS_ReadFrameFromHub
- GalSS_FlushHubWriteQueue
- GalSS_CloseHubConnection
- GalSS_HubReconnectInit
- GalSS_ForceReturn
- GalSS_EnvForceReturn
The following functions have been moved from the core into the MIT dialogue
control library, until they can be replaced by MIT:
- Gal_SetServerName
- Gal_GetServerName
The following functions remain in the core library to support MIT dialogue
control, until they can be replaced by MIT:
- GalSS_DispatchViaHub
- GalSS_WriteFrameToHub
- Incompatible change. Due to improvements in outgoing brokering,
the function GalIO_BrokerDataOutInit
has a new argument list, a number of new functions have been added, and
the function GalIO_FrameGetBrokerPort has been removed. See the upgrade notes.
- Incompatible change. Due to a number of protocol changes
to support better handshaking and improved outgoing brokering, the 3.0 distribution
is not on-the-wire compatible with 2.x. Some of these changes involve modified
handshakes and message encoding, and others involve some modifications to
the distinguished keys used
in the protocol.
- Incompatible change. Due to the new reorganization in the
Hub of servers into service types and providers, the -locations command line argument
no longer overwrites CLIENT_PORT:directives.
- Incompatible change. The flags controlling server listener
status, first introduced in version 2.1, have been changed slightly in connection
with upgraded outgoing brokering. See the upgrade notes.
- Incompatible change. In connection with improving session
management, the semantics of GalSS_EnvError and GalSS_EnvDestroyToken
have changed slightly; the return value from a dispatch function which
calls them is now ignored, rather than being treated as a new message. See
the upgrade
notes.
- Incompatible change. Due to the revised handshaking protocol,
broker clients can no longer contact a broker server running in the same
server as the broker client in non-threaded mode. This restriction can be
fixed if it turns out to be important.
- Incompatible change. The internal reader functions Gal_ReadObjectLine,
Gal_ReadBinary, Gal_ReadString, Gal_ReadFrame, Gal_ReadList, and Gal_ReadObject
have been made static and are no longer externally visible. These functions
were never intended to be used by the programmer, and we doubt that anyone
uses them.
- Incompatible change. As a result of cleaning up the internal
processing in the Hub, a number of functions in the API now have slightly
different function signatures. These functions should only have been used
internally anyway, so no user programs should be affected. The functions
are:
- Gal_ReadProgramLine
- Gal_PrintTests
- Gal_PrintCondition
- Gal_TestCondition
- Gal_NewCondition
- Gal_ReadProgramLine
In addition, the types Gal_FileStruct and Gal_ConditionStruct no longer
have the aliases FileStruct and ConditionStruct. - Incompatible change.
The following utility functions have been removed because they are not used,
and were only intended to be used internally:
- __GalUtil_MaybeByteSwapVector
- __GalUtil_LittleEndianMaybeByteSwapVector
- GalUtil_SockReadIntWithTimeout
- GalUtil_SockWriteFloat
- GalUtil_SockWriteAtom
- GalUtil_SockReadShortArray
- GalUtil_SockReadAtomWithTimeout
- GalUtil_SockReadInt
- GalUtil_SockReadFloat
- GalUtil_SockWriteInt
- GalUtil_SockAllocReadString
- GalUtil_SockReadString
- GalUtil_SockReadAtom
- Incompatible change. The deprecated construct using the
:timestamp key to indicate the timestamping of a bare key
in Hub logging has been removed.
MIT contributions
MITRE contributions
- It is now possible to conditionalize Allegro and Python servers
using the *features* list in the same way that C servers can be
conditionalized using the #define for GC_VERSION. Like
C, Allegro supports read/compile time conditionalization via features; the
Allegro feature for 3.0 is :gc-version-3. Python only supports
runtime conditionalization; the Python feature is Galaxy.GC_VERSION,
the value of which is identical to the C value. You can distinguish in Python
between 3.0 and pre-3.0 libraries by checking for the presence of GC_VERSION
in the Galaxy module. Java is a compiled language which has no
compile-time conditionalizations that we can find, so this feature is unfortunately
unavailable in Java.
- In order to better ensure consistency across programming languages,
the Allegro and Python bindings now rely on the C library. This change should
be invisible to the server developer. We have preserved Java as a natively
implemented binding.
- As a result of relying on the C library for Allegro bindings (see
below), the longstanding bug where Allegro servers don't allow their sockets
to be reused promptly has been fixed.
- The MITRE toy travel demo has been upgraded to use all the current
session management utilities.
- We've made significant improvements to the MITRE PostGres database
wrapper.
- This distribution contains the very latest XML log analysis tools
distributed in 2.0p3 and 2.1p1.
- We have fixed an insidious bug in the stdin polling utility which
manifested itself during the upgrade to 3.0.
- In 2.1, there was an inconsistency between the behavior of programming
language bindings in the listener-in-Hub
case and the C library, where the programming language bindings would shut
down after the last Hub disconnected. As a result of relying on the C library
for Python and Allegro bindings, this inconsistency has been resolved.
- Brokering of floats now works correctly in Allegro.
- It is now possible to initialize Python and Allegro server objects
with keyword arguments as well as command line arguments.
- The following classes have been added to the Java bindings:
- The following methods have been added to the Java bindings:
- The following methods are deprecated
as of 3.0:
- galaxy.lang.BinaryObject has been deprecated as of 3.0.
As a result, the byte[]-based constructors for the array objects
have also been deprecated as have the various to<data type>Array()
methods. The default constructors for the array objects have been changed
to create empty arrays of the appropriate type (e.g., galaxy.lang.Int32
objects have arrays of ints). New local append methods for the
array objects have also been added to accept the appropriate data types,
getBytes returns the array as an array of bytes, and getSize
will return the length of the data type array (if the object was initialized
with a byte array, the length of that array is returned). Finally, the use
of these BinaryObject methods on array objects are deprecated:
- getBytes
- toString
- toEncodedString
- toFormattedString
- The Java class galaxy.lang.GBinary
has taken on galaxy.lang.BinaryObject's "binary data" role. In
particular, GBinary
now has these local methods:
- In the Java bindings, the environment object has been moved out
of galaxy.server.Server
and implemented as the object galaxy.server.Environment.
- A Java server can now postpone a reply to a Hub message. See the
Java
bindings documentation for details.
- See the Java bindings documentation for the new, preferred way
to send new messages and replies to the Hub from a server
or incoming
broker.
- galaxy.server.MainServer
has a new constructor
that takes in a server name and the array of command line arguments. It
can initialize itself with the values of -port, -assert, -maxconns,
-contact_hub, -session_id, and -validate.
This simplifies the development of servers that do not rely on a user interface
(e.g., as provided by galaxy.server.ServerUI).
- The Java class galaxy.util.ArgParser
has a new method getStringArg
for accessing the string value of a command line argument (if appropriate).
- Additional frame key type definitions have been added to the Java
class galaxy.lang.GFrame.
- There is now support for the -maxconns command
line argument in the Java bindings. Also, if both the -port
and -contact_hub command line arguments are specified, the
server will act as a listener AND Hub client. Finally, if the -assert
command line argument is specified, and -port has also been specified,
the server will fail to establish a listener if it cannot obtain the specified
port (or the default port if the -port argument is not used with
-assert).
- Enabled support for appending to a log file in the Java bindings
(this had been unimplemented previously).
- Added support for the -server_locations_file command
line argument in the Java bindings.
- Incompatible change. The Java bindings no longer treat the
colon (:) character in any special way when processing frames. In particular,
colons are no longer prepended to the names of keys and frame names are no
longer prevented from beginning with a colon.
- Incompatible change. As a result of relying on the C library
for Python and Allegro bindings, the installation procedure is slightly different.
The Allegro bindings now require Allegro 5.0 or later, and the Python bindings
require access to the Python header files. See the installation notes.
- Incompatible change. As a result of improving outgoing brokering,
the API for setting up an outgoing broker in the various programming language
bindings has changed, as well as the argument list for MGal_AddOutgoingBrokering().
See the upgrade
notes.
- Incompatible change. For consistency with the rest of the
system, the values controlling "raw" vs. pretty printing in the Allegro
bindings have been changed from :pr and :pp to galaxy::*GAL-PR-PRINT*
and galaxy::*GAL-PP-PRINT*.
- Incompatible change. As a result of relying on the C library
for Python bindings, the method ReadFrameFromString() of the Galaxy.Frame
class has been removed. The Galaxy.OPr() function no longer accepts
the indent keyword. A number of attributes of the GalaxyIO.Server
class have been replaced with methods to access the underlying C functionality:
- the port attribute is now the ListenPort() method
- the validate attribute is now the Validating() and
EnableValidation() methods
- the server_name attribute is now the ServerName()
method
- the max_connections attribute is now the MaxConnections()
method
Finally, as part of the deprecation process, the Galaxy.ValueWarn()
function has been removed. See the upgrade notes and
the implementation of the Python bindings for more details. - Incompatible
change. The (undocumented) TkMGalaxy module has been cleaned up, and
some non-central functionality has been moved elsewhere. See contrib/MITRE/servers/src/ui/py_gui_ui.py.
If you import this module, your code will need to be updated.
- Incompatible change. In support of more robust session support,
and to reduce confusion, the Python GalaxyIO.Connection class has
finally been renamed GalaxyIO.CallEnvironment, which has been its
actual function since Galaxy Communicator 2.0. See the upgrade notes.
- Incompatible change. Looking forward to better Python support
on Windows NT, we have simplified and changed the way Python servers are
configured to get access to the core Python libraries. See the upgrade notes.
- Incompatible change. See the upgrade notes
for changes to the procedure for starting galaxy.server.DataInBroker
threads.
- Incompatible change. See the upgrade
notes for details on new methods that must be implemented by subclasses
of galaxy.server.DataInBroker.
Incompatible change. See the upgrade
notes for a list of methods removed from the interface of galaxy.server.DataOutBroker.
- Incompatible change. See the upgrade notes for
changes in thread management in the Java bindings.
- Incompatible change. See the upgrade
notes for changes to the command line arguments used in the Java bindings.
- Incompatible change. See the upgrade
notes for other miscellaneous changes to the Java bindings.
Known bugs
- In rare cases, if two broker servers attempt to contact each other
simultaneously, a deadlock will arise. This bug is fixable, but would require
some serious internal reorganization.
- If you ask the Hub on NT to read a program file which was written
on Unix, the Hub will fail due to the difference in line breaks between platforms.
This bug has apparently been lurking for quite a while.
- Some of the specialized Makefile behavior seems to exhibit some
small bugs (for instance, "make distclean" appears to do contrib/MITRE twice).
- The tool which automatically generates the PDF documentation from
the HTML documentation does a good but not great job, and in some cases the
formatting is quite odd.
Wish list
This list contains some of the features we had hoped to include in version
3.0 but didn't have time for.
- The Hub program file reader does not yet warn developers when they
appear to be trying to use extended syntax features in non-extended mode.
- The Hub session history DB has not been incorporated into the extended
syntax paradigm.
- The dispatch_token Builtin dispatch function is not capable of
returning the result state.
- The extended syntax mode in Hub programs does not implement things
like explicit reference to frame types and names, attribute paths through
frames, etc., although the infrastructure to support for these references
is already present.
- Server locations files do not support servers contacting multiple
Hubs.
- It should be possible to provide a much better encapsulation of
broker information. We have included protocol support for a proxy data type
in frames, but no API support yet.
- We had hoped to provide real Python support for NT.
- We had hoped to improve the PostGres wrapper in a number of ways
we haven't had a chance to address yet.
- We have not yet updated the correspondences between C and Python/Allegro
API calls.
Last modified January 18, 2002