Galaxy Communicator Documentation:

Setting Up Listeners in the Hub

License / Documentation home / Help and feedback

By default, each Communicator server sets up a socket-based listener for the Hub to contact. As of version 2.1, it is  possible to reverse the direction of this connectivity, by setting up listeners in the Hub instead. This has a number of clear advantages:

This functionality supersedes dispatch servers, which have been removed in version 3.0.


Setting up the Hub

The Hub needs to know that it's supposed to set up a listener. To do this, use the CLIENT_PORT: declaration in your SERVICE_TYPE: declaration:
SERVICE_TYPE: parser
OPERATIONS: parse
CLIENT_PORT: 15000
When the Hub starts up, it will start a listener on port 15000 (or the next available port) and wait for connections. You can have as many or as few listeners as you want, and as many servers as you want can share a listener:
SERVICE_TYPE: parser
OPERATIONS: parse
CLIENT_PORT: 15000

SERVICE_TYPE: recognizer
OPERATIONS: recognize
CLIENT_PORT: 15000

SERVICE_TYPE: database
OPERATIONS: retrieve
CLIENT_PORT: 14000

SERVER: generator
OPERATIONS: generate
HOST: localhost
PORT: 18000

In this example, the Hub will start up two listeners, one on port 15000 (shared by the parser and recognizer) and one on port 14000 (used exclusively by the database), and attempt to contact the generator on its own listener on port 18000. Listeners are shared based on the requested client port; so if port 15000 is taken, the Hub will start up a shared listener for the parser and recognizer on the next available port.

Important: The Hub relies on the connecting server to identify itself by name in order to determine which of the server types to identify the new connection with. Therefore, unlike in normal server entries, the value of SERVER: or SERVICE_TYPE: must match the name the contacting server knows itself as.


Setting up the server

Setting up the server is also simple. It involves the server command line arguments -contact_hub and -session_id. The -contact_hub argument provides a space-delimited sequence of host:port entries to contact Hubs at; the -session_id argument locks the server connection to the named user session (and creates the session if it does not already exist). So the parser or database might contact the Hub configured above as follows:
% parser -contact_hub "localhost:15000"
If the server in question is a UI element (say, an audio connection), you might want to associate it with a specific session:
% audio -contact_hub "localhost:2400" -session_id 20000711session1
If you use the -session_id command line argument, it's equivalent to setting all the session lock flags for this server.

You can contact several Hubs at once:

% database -contact_hub "localhost:15000 remotehost:25000"
The server will poll the connection location until it establishes a connection, and will start polling again when the Hub disconnects; it's possible to customize this behavior if you write your own main function.


The handshake protocol

The initial handshake between the Hub and servers is slightly different in the listener-in-Hub case. In particular, since the Hub needs to know immediately what the server's name is, the handshake begins with the server sending a message to the Hub, which allows the Hub to set up the connection appropriately or reject it. Once this stage of the handshake is complete, the normal initialization procedure continues, with the Hub sending the reinitialize message to the server.


API support

For API support for this functionality, see the server structure documentation.


License / Documentation home / Help and feedback
Last updated July 5, 2002