Galaxy Communicator Documentation:

MITRE Python Bindings


Enabling Python bindings

See the installation documentation for how to enable the Python bindings. Python 1.5 or later is required.


Documentation Summary

The bindings are divided into files which correspond approximately to subdirectories of libGalaxy: Galaxy.py (galaxy), GalaxyIO.py (io and ServerStub), MGalaxy.py (MITRE's libMITREgalaxy), and SLSUtil.py (util). There is a final module, cGalaxy, which is implemented in C and provides a wrapper around the core Galaxy Communicator library.

The following demos contain Python server examples. All examples can be found in the python/ subdirectory of these demos:

The Python versions in these examples are, to the greatest extent possible, exact parallels of the C versions, so you can study the two versions side by side.

Among the major differences from the C bindings are:

At the moment, the source code and examples will serve as the primary documentation. However, we provide details and a table of equivalences as a guide.


Details

We will follow the general outline of the tutorial. Most of the lessons apply just as well to the Python bindings as to the core C library. We address the important differences here.

Introducing frames and objects

In general, because Python is a dynamically typed language and supports dictionaries whose objects can be of heterogeneous types, the wrappers for building objects are superfluous. Here are some of the examples from the frame tutorial, translated into Python:
import Galaxy

# {c output :output_string "hello" }

f = Galaxy.Frame("output", Galaxy.GAL_CLAUSE)
f[":output_string"] = "hello"

# or

f = Galaxy.Frame("output", Galaxy.GAL_CLAUSE, {":output_string": "hello"})

# {c listframe :list ( 5 6 7 ) }

f = Galaxy.Frame("listframe", Galaxy.GAL_CLAUSE)
f[":list"] = [5, 6, 7]

# or

f = Galaxy.Frame("listframe", Galaxy.GAL_CLAUSE, {":list": [5, 6, 7]})

Server basics

In order to access the Python bindings, we recommend the following idiom:
import sys, os

sys.path.insert(0, os.path.join(os.environ["GC_HOME"],
                                "contrib", "MITRE", "templates"))

import GC_py_init

import Galaxy, GalaxyIO, SLSUtil

Alternatively, instead of assuming the presence of GC_HOME in your environment, you could find another way to make the GalaxyCommunicator root directory available to your program.

Each dispatch function takes an environment object and a frame and returns a dictionary or frame. In the case of Python, the call environment is the first argument, so that methods on classes inherited from GalaxyIO.CallEnvironment also have the same signature.

Here's a Python equivalent of the Parse dispatch function:

def Parse(env, frame):
    input_string = frame[":input_string"]
    p = ParseSentence(input_string)
    return {":frame": ParseTreeToFrame(p)}
Note that we can return a dictionary, instead of a named frame, since the name of the reply is ignored anyway. The dictionary will be coerced into an appropriate reply frame.

Python doesn't use macros to generate the declaration of dispatch functions or the name and default port information for the server. This is all handled via explicit function calls:

class ParseServer(GalaxyIO.Server):
   ...

s = ParseServer(sys.argv, "Parser", default_port = 10000)
s.AddDispatchFunction("Parse", Parse)

Note that because the dispatch functions are explicitly associated with their names, the name of the function and the name of the message that invokes it can differ.

Here's another way to set up your server, by using methods as dispatch functions:

class ParseEnvironment(GalaxyIO.CallEnvironment):
    def Parse(self, frame):
        input_string = frame[":input_string"]
        p = ParseSentence(input_string)
        return {":frame": ParseTreeToFrame(p)}

...

s = ParseServer(sys.argv, "Parser", default_port = 10000,
                env_class = ParseEnvironment)
s.AddDispatchFunction("Parse", ParseEnvironment.Parse)

You can use the specialized classes for the call environment or for the server to store arbitrary data as instance variables.

By default, Python servers accept approximately the same set of default arguments as C servers. The differences are:

The Python bindings include a set of functionality equivalent to the core C argument parsing library. This functionality is exemplified in the Python version of the double server:
OAS = [("-increment i", "initial increment")]

# Write a wrapper for the usage check.

class DoubleServer(GalaxyIO.Server):
    def CheckUsage(self, oas_list, args):
        global InitialIncrement
        data, out_args = GalaxyIO.Server.CheckUsage(self, OAS + oas_list, args)
        if data.has_key("-increment"):
            InitialIncrement = data["-increment"][0]
            del data["-increment"]
        return data, out_args

Note that we check command line arguments by creating a wrapper around the CheckUsage method of the server object. This method returns a dictionary whose keys are the argument names and whose values are a list of elements, as well as a sequence of unanalyzed arguments. If the argument list does not parse (if, for instance, some expected parameters of a given command line argument are missing), the server will exit. Here's a more complex example of an initialization string:
OAS = [("-utts utts_file num", "text utterance file for sequencing",
       (types.StringType, types.IntType), (Utterance_File, 0)]
       ("-stdin", "Read sentences from stdin instead of a file")]
The first element is the argument, with spaces delimiting the parameters. The second is a description. Both of these elements are as in the the oa library. The third element, if present, is a sequence of  types, and the fourth element, if present, is a sequence of defaults. If there aren't enough types, types.StringType is used; if there is a defaults list but not enough defaults, the appropriate null value is used (0, 0.0, or ""). If the fourth element is present, the return dictionary will contain the defaults if the argument is not present in the arglist.

Error handling

Unlike C, Python has try/except for raising and catching errors. If you raise an error in a dispatch function (intentionally or otherwise), the Python bindings will catch the error and convert it to an error reply. Here's the Parse function again:
import types

ParseError = "ParseError"

def Parse(env, frame):
    try:
        input_string = frame[":input_string"]
    except KeyError:
        input_string = None
    if (type(input_string) is not type("")):
        raise ParseError, "no input string"
    p = ParseSentence(input_string)
    if not p:
        raise ParseError, "no parse"
    p_frame = ParseTreeToFrame(p)
    if not p_frame:
        raise ParseError, "can't convert parse to frame"
    return {":frame": p_frame}

Sending new messages to the Hub

Sending asynchronous and synchronous messages to the Hub works pretty much as you might anticipate. Let's start with the DoGreeting case:
def DoGreeting(env, frame):
    s = "{c FromDialogue :output_frame {c greeting } :is_greeting 1 }"
    greeting = Galaxy.Frame(str = s)
    env.WriteFrame(greeting)
    return None
If you want to return no frame to the Hub, you must return None; an empty dictionary will return an empty frame.

Now, here's the DoDialogue example:

def DoDialogue(env, frame):
    msg_frame = Galaxy.Frame("DBQuery", Galaxy.GAL_CLAUSE)

    # ...

    msg_frame[":sql_query"] = sql_query
    try:
        response_frame = env.DispatchFrame(msg_frame)
        # Equivalent of GAL_REPLY_MSG_TYPE.
        # Construct presentation of database response
        # ...
    except GalaxyIO.DispatchError:
        # Equivalent of GAL_ERROR_MSG_TYPE
        # Relay error back to Hub
        # ...

If the Hub relays an error back to the server, the Python bindings will raise the error locally. The error raised will be GalaxyIO.DispatchError, as shown here.

Setting up a brokered audio connection

In order to set up a broker server, you can use the class GalaxyIO.BrokerDataOut directly, most of the time. For the broker client, you should subclass GalaxyIO.BrokerDataIn. The methods EnvHandleFrame, EnvHandleString, EnvHandleBinary, EnvHandleInt16, etc., can be subclassed on the broker client to handle the appropriate class of incoming data. Outgoing data is handled using the Write method; there is no need for separate functions to write each datatype.

Here's the equivalent of the Synthesize dispatch function, exemplifying the source server setup. If the broker setup fails, an error is raised:

def Synthesize(env, frame):
    # ...
    try:
        b = GalaxyIO.BrokerDataOut(env.conn, 10)
        output_f = Galaxy.Frame("FromSynthesizer", Galaxy.GAL_FRAME,
                                {":sample_rate": s.sample_rate,
                                 ":encoding_format": s.encoding_format})
        b.PopulateFrame(output_f, ":host", ":port")
        env.WriteFrame(output_f)
    except GalaxyIO.BrokerInitError, m:
        # ....
Now, here's the setup for the client:
class AudioBroker(GalaxyIO.BrokerDataIn):
    # ...

def Play(env, frame):
    host = frame[":host"]
    port = frame[":port"]
    p = AudioPkg()

    # ...

    try:
        p.in_broker = AudioBroker(env, host, port, frame)
        p.in_broker.AddCallback(GalaxyIO.GAL_BROKER_DATA_DONE_EVENT,
                                lambda b = p.in_broker: b.__AudioOutputCallback)
        # ...
    except GalaxyIO.BrokerInitError, m:
        # ...

The data exchange works as follows. First, on the source server:
data = PollSynthesis(s)

while data:
    b.Write(data)
    data = PollSynthesis(s)
if SynthesisIsDone(s):
    b.DataDone()

On the client, it's handled as methods associated with the specialized broker class:
class AudioBroker(GalaxyIO.BrokerDataIn):
    def EnvHandleInt16(self, env, obj):
        print "[Audio data to user (%d samples)]" % len(obj)
Unhandled data types raise GalaxyIO.BrokerProcessingError.


Equivalences

These functions are arranged in alphabetical order of the corresponding C functions, arranged by the documents in the advanced and reference sections of the documentation which describe those functions.
 
Frames, Property Lists, and Typed Objects  
 
GalUtil_CPPFrame(sls_verbose_level, fore, back, fr) [not implemented]
GalUtil_CPPObject(sls_verbose_level, fore, back, o) [not implemented]
GalUtil_PPFrame(verbose_level, fr) SLSUtil.OStream().write_level(fr.PPrint(), verbose_level)
GalUtil_PPObject(verbose_level, o) SLSUtil.OStream().write_level(Galaxy.OPr(o, PP_TYPE), verbose_level)
GalUtil_PrObject(verbose_level, o) SLSUtil.OStream().write_level(Galaxy.OPr(o), verbose_level)
GalUtil_PrintObject(verbose_level, o, how) SLSUtil.OStream().write_level(Galaxy.OPr(o, how), verbose_level)
Gal_AddPred(fr, pred) fr.preds.append(pred)
Gal_ArrayObjectAdd(obj, data, size) obj = obj + data
Gal_BinaryObject(data, size) Galaxy.BinaryObject(Galaxy.GAL_BINARY, data)
Gal_BinarySize(obj) len(obj)
Gal_BinaryValue(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_BINARY)
Gal_Binaryp(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_BINARY
Gal_ClauseFramep(fr) Galaxy.GetDetailedType(fr) == Galaxy.GAL_CLAUSE
Gal_ClauseValue(o) [not implemented]
Gal_Clausep(obj) Galaxy.GetDetailedType(obj) == Galaxy.GAL_CLAUSE
Gal_ClearPreds(fr) fr.preds = []
Gal_CopyFrame(fr) fr.Copy()
Gal_CopyObject(obj) [not implemented]
Gal_CreateBinaryObject(data, size, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_BINARY, data)
Gal_CreateFloat32Object(data, num_float_32, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_FLOAT_32, data)
Gal_CreateFloat64Object(data, num_float_64, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_FLOAT_64, data)
Gal_CreateFloatObject(value, manage_memory) [not needed]
Gal_CreateFrameObject(value, manage_memory) [not needed]
Gal_CreateInt16Object(data, num_int_16, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_INT_16, data)
Gal_CreateInt32Object(data, num_int_32, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_INT_32, data)
Gal_CreateInt64Object(data, num_int_64, manage_memory) Galaxy.BinaryObject(Galaxy.GAL_INT_64, data)
Gal_CreateListObject(values, n, free_fn , manage_memory) [not needed]
Gal_CreateStringObject(cp, manage_memory) [not needed]
Gal_CreateVarMapping(num_pairs, ...) [not implemented]
Gal_DelPred(fr, i) del f.preds[i]
Gal_DelPredByName(fr, name) p = f.GetPredByName(name); f.preds.remove(p)
Gal_DelProp(fr, key) del f[key]
Gal_DeletePreds(fr, pred_name) [not implemented]
Gal_DoPreds(fr, pred_fn , caller_data) map(pred_fn, fr.preds)
Gal_DoProperties(fr, prop_fn , caller_data) map(prop_fn, fr.items())
Gal_FindKey(fr, key_name) [not implemented]
Gal_FindPred(fr, pred_name) [not implemented]
Gal_FindPredParent(frame, name, parent, findpar, nth) [not implemented]
Gal_FindTopic(fr, topic_name) [not implemented]
Gal_Float32Size(o) len(o)
Gal_Float32Value(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_FLOAT_32)
Gal_Float32p(o) Galaxy.GetObjectType(o) == Galaxy.GAL_FLOAT_32
Gal_Float64Size(o) len(o)
Gal_Float64Value(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_FLOAT_64)
Gal_Float64p(o) Galaxy.GetObjectType(o) == Galaxy.GAL_FLOAT_64
Gal_FloatObject(val) [not needed]
Gal_FloatValue(o) Galaxy.ValueWarn(o, Galaxy.GAL_FLOAT)
Gal_Floatp(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_FLOAT OR type(obj) is types.FloatType
Gal_FrameEqual(sf1, sf2) sf1.Equal(sf2)
Gal_FrameIsType(fr, type) fr.type == type
Gal_FrameName(fr) fr.name
Gal_FrameNameEq(fr, name) fr.name == name
Gal_FrameNamesEq(fr1, fr2) fr1.name == fr2.name
Gal_FrameObject(val) [not needed]
Gal_FrameValue(o) Galaxy.ValueWarn(o, Galaxy.GAL_FRAME)
Gal_Framep(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_FRAME
Gal_FreeFrame(fr) [not needed]
Gal_FreeObject(obj) [not needed]
Gal_FreeWrapper(to) [not needed]
Gal_GetBinary(fr, key, size) fr.GetValue(key, Galaxy.GAL_BINARY)
Gal_GetDetailedType(o) Galaxy.GetDetailedType(o)
Gal_GetFloat(fr, key) fr.GetValue(key, Galaxy.GAL_FLOAT)
Gal_GetFloat32(fr, key, size) Galaxy.ValueWarn(obj, Galaxy.GAL_FLOAT_32)
Gal_GetFloat64(fr, key, size) Galaxy.ValueWarn(obj, Galaxy.GAL_FLOAT_64)
Gal_GetFrame(fr, key) fr.GetValue(key, Galaxy.GAL_FRAME)
Gal_GetFrameType(fr) fr.type
Gal_GetInt(fr, key) fr.GetValue(key, Galaxy.GAL_INT)
Gal_GetInt16(fr, key, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_16)
Gal_GetInt32(fr, key, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_32)
Gal_GetInt64(fr, key, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_64)
Gal_GetList(fr, key, length) fr.GetValue(key, GAL_LIST)
Gal_GetListObject(obj, n) obj[n]
Gal_GetListValue(o, n, type) Galaxy.ValueWarn(o[n], type)
Gal_GetObject(fr, key) fr[key]
Gal_GetObjectType(o) Galaxy.GetObjectType(o)
Gal_GetObjectTypeString(o) Galaxy.ObjectTypeString(Galaxy.GetObjectType(o))
Gal_GetPred(fr, i) fr.preds[i]
Gal_GetPredByName(fr, name) fr.GetPredByName(name)
Gal_GetProperties(fr, nkeys) fr.keys()
Gal_GetString(fr, key) fr.GetValue(key, Galaxy.GAL_STRING)
Gal_GetTopicFrame(fr, key) [not implemented]
Gal_Int16Size(o) len(o)
Gal_Int16Value(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_16)
Gal_Int16p(o) Galaxy.GetObjectType(o) == Galaxy.GAL_INT_16
Gal_Int32Size(o) len(o)
Gal_Int32Value(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_32)
Gal_Int32p(o) Galaxy.GetObjectType(o) == Galaxy.GAL_INT_32
Gal_Int64Size(o) len(o)
Gal_Int64Value(obj, size) Galaxy.ValueWarn(obj, Galaxy.GAL_INT_64)
Gal_Int64p(o) Galaxy.GetObjectType(o) == Galaxy.GAL_INT_64
Gal_IntObject(val) [not needed]
Gal_IntValue(to) Galaxy.ValueWarn(obj, Galaxy.GAL_INT)
Gal_Intp(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_INT OR type(obj) is types.IntType
Gal_ListLength(obj) len(obj)
Gal_ListObject(values, n) [not needed]
Gal_ListObjectAdd(obj, elt) obj.append(elt)
Gal_ListObjectFromElements(n, ...) [not needed]
Gal_ListValue(obj, n) Galaxy.ValueWarn(obj, Galaxy.GAL_LIST)
Gal_Listp(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_LIST OR type(obj) is types.ListType
Gal_MakeClauseFrame(name) Galaxy.Frame(name = name, type = Galaxy.GAL_CLAUSE)
Gal_MakeFrame(name, type) Galaxy.Frame(name = name, type = type)
Gal_MakePredFrame(name) Galaxy.Frame(name = name, type = Galaxy.GAL_PRED)
Gal_MakeTopicFrame(name) Galaxy.Frame(name = name, type = Galaxy.GAL_TOPIC)
Gal_MatchFrame(sf1, sf2) [not implemented]
Gal_MatchKeyValue(fr, key_name, match) [not implemented]
Gal_NumNonNullProperties(fr) len(fr)
Gal_NumPreds(fr) len(fr.preds)
Gal_NumProperties(fr) len(fr)
Gal_ObjectByteCount(obj) [not implemented]
Gal_ObjectCaseEqual(obj1, obj2) Galaxy.ObjectEqual(obj1, obj2, ignore_case = 1)
Gal_ObjectEqual(obj1, obj2) Galaxy.ObjectEqual(obj1, obj2)
Gal_ObjectToString(o) Galaxy.OPr(o)
Gal_ObjectTypeString(object_type) Galaxy.ObjectTypeString(object_type)
Gal_OutlineFrame(fr, sls_verbose_level) [not implemented]
Gal_OutlineObject(to, sls_verbose_level) [not implemented]
Gal_PPFrame(fr) print fr.PPrint() OR fr.PP()
Gal_PPFrameToFile(fr, fp) fp.write(fr.PPrint())
Gal_PPFrameToString(fr, buf, bufsizeptr) fr.PPrint()
Gal_PPObject(o) print Galaxy.OPr(o, Galaxy.PP_TYPE)
Gal_PPObjectToFile(o, fp) fp.write(Galaxy.OPr(o, Galaxy.PP_TYPE))
Gal_PrFrame(fr) print fr.Print() OR f.rPr()
Gal_PrFrameToFile(fr, fp) fp.write(fr.Print())
Gal_PrFrameToString(fr, buf, bufsizeptr) fr.Print()
Gal_PrObject(obj) print Galaxy.OPr(obj) OR Galaxy.PrObject(obj)
Gal_PrObjectToFile(obj, fp) fp.write(Galaxy.OPr(obj))
Gal_PredFramep(fr) Galaxy.GetDetailedType(obj) == Galaxy.GAL_PRED
Gal_PredValue(to) [not implemented]
Gal_Predp(obj) Galaxy.GetDetailedType(obj) == Galaxy.GAL_PRED
Gal_PrintFrameToFile(fr, fp, how) fp.write(fr._Print(how))
Gal_PrintFrameToString(fr, irpbuf, bufsizeptr, how) fr._Print(how)
Gal_ReadFrameFromFile(fp) [not implemented]
Gal_ReadFrameFromString(buf) Galaxy.Frame(str = buf)
Gal_ReadObjectFromFile(fp) [not implemented]
Gal_ReadObjectFromString(buf) Galaxy._read_irp_value(buf)
Gal_ReadVarFrameFromString(buf, map) [not implemented]
Gal_RemPred(fr, i) p = fr.preds[i]; del fr.preds[i]; return p
Gal_RemPredByName(fr, name) p = fr.GetPredByName(name); fr.preds.remove(p); return p
Gal_RemProp(fr, key) p = fr[key]; del fr[key]; return p
Gal_SetFrameName(fr, name) fr.name = name
Gal_SetFrameType(fr, type) fr.type = type
Gal_SetProp(fr, key, obj) fr[key] = obj
Gal_StringObject(val) [not needed]
Gal_StringValue(to) Galaxy.ValueWarn(obj, Galaxy.GAL_STRING)
Gal_Stringp(obj) Galaxy.GetObjectType(obj) == Galaxy.GAL_STRING OR type(obj) is types.StringType
Gal_TopicFramep(fr) Galaxy.GetDetailedType(obj) == Galaxy.GAL_TOPIC
Gal_TopicValue(to) [not implemented]
Gal_Topicp(obj) Galaxy.GetDetailedType(obj) == Galaxy.GAL_TOPIC
Gal_VAReadVarFrameFromString(buf, num_pairs, ...) [not implemented]
_gal_free_object(obj) [not needed]
 
Building a Communicator-Compliant Server  
 
GalIO_GetError(f, err_desc) [not needed; just catch GalaxyIO.DispatchError]
GalSS_AddDispatchFunction(i, name, fn, in_key_array, allow_other_in_keys, reply_provided, out_key_array, allow_other_out_keys) i.AddDispatchFunction(...)
GalSS_EnvDestroyToken(env) env.DestroyToken()
GalSS_EnvDispatchFrame(env, frame, t) env.DispatchFrame(frame)
GalSS_EnvError(env, description) [not needed; just raise an error]
GalSS_EnvGetClientData(env, name) [not needed; use instance attributes]
GalSS_EnvGetCommData(env) [not needed; use instance attributes]
GalSS_EnvReply(env, f) env.Reply(f)
GalSS_EnvSetCommData(env, data, free_fn ) [not needed; use instance attributes]
GalSS_EnvWriteFrame(env, frame, do_block) env.WriteFrame(frame)
GalSS_InitializeServerDefaults(scomm, name, port) [not implemented]
Gal_CreateDispatchFnKeyArray(ignore, ...) [not needed]
Gal_FreeDispatchFnKeyArray(entry) [not needed]
_GalSS_InitializeDefaults(scomm) [not needed; provided to scomm during initialization]
_GalSS_init_server(server, argc, argv) [not needed; perform operations after initialization and before starting server]
_GalSS_print_usage(argc, argv) [not implemented]
 
Brokering and Audio Data  
 
GalIO_BrokerDataDone(b) b.DataDone()
GalIO_BrokerDataInInit(host, port, frame, fnptr, caller_data, poll_ms) [not implemented]
GalIO_BrokerDataOutDone(b) b.DataDone()
GalIO_BrokerDataOutInit(gcomm, poll_ms, timeout_seconds) b = GalaxyIO.BrokerDataOut(gcomm, timeout_seconds)
GalIO_BrokerIsDone(b) [not implemented]
GalIO_BrokerPopulateFrame(b, f, host_key, port_key) b.PopulateFrame(f, host_key, port_key)
GalIO_BrokerSetFinalizer(b, finalizer) [not implemented]
GalIO_BrokerStructDequeue(b, bqueue) [not needed; no broker queues in Python]
GalIO_BrokerStructQueueAppend(b, bqueue) [not needed; no broker queues in Python]
GalIO_BrokerStructQueuePop(bqueue) [not needed; no broker queues in Python]
GalIO_BrokerWriteBinary(b, data, n_bytes) b.Write(data)
GalIO_BrokerWriteFloat(b, f) b.Write(f)
GalIO_BrokerWriteFloat32(b, data, n_floats) b.Write(data)
GalIO_BrokerWriteFloat64(b, data, n_floats) b.Write(data)
GalIO_BrokerWriteFrame(b, frame) b.Write(f)
GalIO_BrokerWriteInt(b, i) b.Write(i)
GalIO_BrokerWriteInt16(b, data, n_ints) b.Write(data)
GalIO_BrokerWriteInt32(b, data, n_ints) b.Write(data)
GalIO_BrokerWriteInt64(b, data, n_ints) b.Write(data)
GalIO_BrokerWriteList(b, elts, n_elts) b.Write(elts)
GalIO_BrokerWriteObject(b, o) b.Write(o)
GalIO_BrokerWriteString(b, str) b.Write(s)
GalIO_CommBrokerDataInInit(host_gcomm, host, port, frame, fnptr, poll_ms, caller_data, caller_data_free_fn ) b = GalaxyIO.BrokerDataIn(host_gcomm, host, port, frame)
GalIO_ForceBrokerExpiration(b) [not implemented]
GalIO_FrameSetBrokerCallID(f, call_id) [not implemented]
GalIO_GetBrokerCallID(b) b.call_id
GalIO_GetBrokerCallerData(b) [not needed; use instance attributes]
GalIO_GetBrokerData(b) [not needed; use instance attributes]
GalIO_GetBrokerFrame(b) [not implemented]
GalIO_GetBrokerListenPort(b) b.port
GalIO_IPAddress() GalaxyIO.IPAddress()
GalIO_SetBrokerActive(b) [not needed; no broker queues in Python]
GalIO_SetBrokerData(b, caller_data, free_fn ) [not needed; use instance attributes]
GalSS_BrokerGetEnvironment(b) b.env
GalSS_BrokerSetEnvironment(b, env) [not needed; pass environment to BrokerDataIn]
GalSS_EnvBrokerDataInInit(env, host, port, frame, fnptr, poll_ms, refptr, free_fn ) b = GalaxyIO.BrokerDataIn(env, host, port, frame)
 
Server Architecture  
 
GalIO_AddBrokerCallback(b, callback_event, fn, callback_data) b.AddCallback(callback_event, fn)
GalIO_AddConnectionBrokerCallback(gcomm, callback_event, connect_callback, callback_data) [not needed; specialize __init__ method]
GalIO_AddConnectionCallback(gcomm, callback_event, connect_callback, callback_data) [not implemented]
GalIO_AddConnectionDispatchFnCallback(gcomm, dispatch_callback, callback_data) [not implemented]
GalIO_AddServerCallback(scomm, callback_event, fn, callback_data) [not implemented]
GalIO_AddServerConnectCallback(scomm, connect_callback, callback_data) [not implemented]
GalIO_CommValidating(gcomm) gcomm.Validating()
GalIO_CommWriteFrame(gcomm, frame, do_block) gcomm.WriteFrame(frame)
GalIO_ContactHub(host, port, scomm, session_id, client_poll_flags) [not implemented]
GalIO_DispatchViaHub(gcomm, frame, msg_type_ptr) gcomm.DispatchFrame(frame)
GalIO_EnableDispatchFnValidation(scomm) scomm.EnableValidation()
GalIO_GetCommClientData(gcomm, name) [not needed; use instance attributes]
GalIO_GetCommData(gcomm) [not needed; use instance attributes]
GalIO_GetCommServerData(gcomm) [not needed; use instance attributes]
GalIO_GetCommServerName(gcomm) gcomm.server.ServerName()
GalIO_GetServerClientData(server, name) [not needed; use instance attributes]
GalIO_GetServerData(scomm) [not needed; use instance attributes]
GalIO_GetServerDefaultPort(scomm) [not implemented]
GalIO_GetServerListenPort(scomm) scomm.ListenPort()
GalIO_GetServerMaxConnections(scomm) scomm.MaxConnections()
GalIO_GetServerName(scomm) scomm.ServerName()
GalIO_GetServerNumConnections(scomm) len(scomm.conns)
GalIO_GetUniqueConnection(scomm) [not implemented]
GalIO_OperateOnConnections(scomm, arg, op ) map(op, scomm.conns.values())
GalIO_RemoveBrokerCallback(b, cb) [not implemented]
GalIO_RemoveConnectionCallback(gcomm, cb) [not implemented]
GalIO_RemoveServerCallback(scomm, cb) [not implemented]
GalIO_ServerListenStatus(scomm) [not implemented]
GalIO_ServerSessionID(scomm) [not implemented]
GalIO_ServerUsesTimedTasks(server) [not implemented; polling by select]
GalIO_SetCommClientData(gcomm, name, client_data) [not needed; use instance attributes]
GalIO_SetCommData(gcomm, data, free_fn ) [not needed; use instance attributes]
GalIO_SetServerClientData(server, name, client_data) [not needed; use instance attributes]
GalIO_SetServerData(scomm, data, free_fn ) [not needed; use instance attributes]
GalIO_SetServerDefaultPort(scomm, port) [not implemented]
GalIO_SetServerMaxConnections(scomm, max) scomm.MaxConnections(max)
GalIO_SetServerName(scomm, name) scomm.ServerName(name)
GalSS_CmdlineInitializeServer(argc, argv) [not implemented]
GalSS_CmdlineSetupServer(argc, argv) [not implemented]
GalSS_DefaultServerArgs() [not needed]
GalSS_EnvComm(env) env.conn
GalSS_ExtractCmdlineServerArgs(arg_pkg, argc, argv, new_argc_ptr, new_argv_ptr) [not needed]
GalSS_ExtractServerArgs(argc, argv, new_argc_ptr, new_argv_ptr) [not needed]
GalSS_FreeArgPkg(arg_pkg) [not needed]
GalSS_InitializeServer(server_port, max_conns, use_color, do_assert, use_ttloop, validate, new_argc, new_argv) [not implemented]
GalSS_InitializeServerFromServerArgs(arg_pkg, new_argc, new_argv) [not implemented]
GalSS_InitializeServerToplevel(server_port, max_conns, use_color, do_assert, loop_type, validate, verbosity, server_listen_status, client_pair_string, session_id, new_argc, new_argv) [not implemented]
GalSS_RunServer(server) [not implemented]
GalSS_SAFixAssert(arg_pkg, assert) [not implemented]
GalSS_SAFixColor(arg_pkg, color) [not implemented]
GalSS_SAFixContactHubInfo(arg_pkg, client_pair_status, session_id, old_session_id_ptr) [not implemented]
GalSS_SAFixLoopType(arg_pkg, loop_type) [not implemented]
GalSS_SAFixMaxConns(arg_pkg, max_conns) [not implemented]
GalSS_SAFixPort(arg_pkg, port) [not implemented]
GalSS_SAFixServerListenStatus(arg_pkg, server_listen_status) [not implemented]
GalSS_SAFixServerLocations(arg_pkg, server_locations_file) [not implemented]
GalSS_SAFixValidate(arg_pkg, validate) [not implemented]
GalSS_SAFixVerbosity(arg_pkg, verbosity) [not implemented]
GalSS_SetupServer(arg_pkg, new_argc, new_argv) GalaxyIO.Server(...)
GalSS_StartAndRunServer(server) s.RunServer()
 
The Timed Task Loop None of these functions are implemtened, because Python doesn't use the timed task loop.
 
Gal_AddIdleFunction(func, client_data) [not implemented]
Gal_AddTask( task , refcon, num_millisecs, read_blocking_available, cleanup_fn ) [not implemented]
Gal_AddTaskExtended( task , caller_data, num_millisecs, read_blocking_available, read_socket, write_socket, err_socket, read_file, write_file, err_file, condition, cleanup_fn ) [not implemented]
Gal_AddTaskWithFileIO( task , refcon, num_millisecs, read_blocking_available, read_file, write_file, cleanup_fn ) [not implemented]
Gal_AddTaskWithSocketIO( task , refcon, num_millisecs, read_blocking_available, read_socket, write_socket, cleanup_fn ) [not implemented]
Gal_AddTimedTask(task, refcon, num_millisecs) [not implemented]
Gal_AddTimedTaskWithFileIO(task, refcon, num_millisecs, read_file, write_file) [not implemented]
Gal_AddTimedTaskWithSocketIO(task, refcon, num_millisecs, read_socket, write_socket) [not implemented]
Gal_EnableTimedTaskThreads() [not implemented]
Gal_EndTasks(immediate) [not implemented]
Gal_MaybeEndTask(immediate, deferred) [not implemented]
Gal_ReAddTask(p, refcon, num_millisecs, read_blocking_available, cleanup_fn ) [not implemented]
Gal_ReAddTaskExtended(p, caller_data, num_millisecs, read_blocking_available, read_socket, write_socket, err_socket, read_file, write_file, err_file, condition, cleanup_fn ) [not implemented]
Gal_ReAddTaskWithFileIO(p, refcon, num_millisecs, read_blocking_available, read_file, write_file, cleanup_fn ) [not implemented]
Gal_ReAddTaskWithSocketIO(p, refcon, num_millisecs, read_blocking_available, read_socket, write_socket, cleanup_fn ) [not implemented]
Gal_RemoveIdleFunction(func) [not implemented]
Gal_RemoveTask(task_id) [not implemented]
Gal_RemoveTimedTask(task, refcon) [not implemented]
Gal_RunIdleFunctions() [not implemented]
Gal_TaskPkgBlocking(pkg) [not implemented]
Gal_TaskPkgData(pkg) [not implemented]
Gal_TaskPkgRunReasons(pkg) [not implemented]
Gal_TimedTaskLoopThreadWaiter() [not implemented]
Gal_TimedTaskThreadsEnabled() [not implemented]
Gal_TimedTasksLoop() [not implemented]
Gal_TimedTasksLoopExit() [not implemented]
Gal_TimedTasksLoopHandler(tv) [not implemented]
 
Managing Session Information and Using Continuations  
 
GalSS_EnvAddTask(env, task , caller_data, num_millisecs, read_blocking_available, read_socket, write_socket, err_socket, read_file, write_file, err_file, condition, cleanup_fn ) [not implemented]
GalSS_EnvCreate(gcomm) GalaxyIO.CallEnvironment(gcomm, None, create_p = 1)
GalSS_EnvDispatchFrameWithContinuation(env, frame, fn, continuation_state, continuation_state_free_fn ) env.DispatchFrameWithContinuation(frame, fn)
GalSS_EnvGetSessionID(env) env.GetSessionID()
GalSS_EnvLock(env) [not needed]
GalSS_EnvMaintainInLocation(gcomm, initial_session_id, env_loc) [not implemented]
GalSS_EnvPostponeReply(env) [not implemented]
GalSS_EnvReturnRequired(env) env.ReturnRequired()
GalSS_EnvUnlock(env) [not needed] 
GalSS_EnvUpdateSessionID(env, session_id) env.UpdateSessionID(session_id)
GalSS_TaskGetEnvironment(p) [not implemented]
GalSS_TaskSetEnvironment(p, env) [not implemented]
 
Controlling Hub Server and Session Properties from the Server  
 
GalIO_AddServiceType(server, stype) server.AddServiceType(stype)
GalIO_ServerModifyProperties(server, new_properties, delete_properties) server.ModifyProperties(new_properties, delete_properties)
GalIO_ServerProperties(server) [not implemented]
GalSS_EnvDeleteServerProperties(env, keys) env.ModifyServerProperties(properties_to_delete = keys)
GalSS_EnvDeleteSessionProperties(env, keys) env.ModifySessionProperties(properties_to_delete = keys)
GalSS_EnvGetServerProperties(env, keys) env.GetServerProperties(keys)
GalSS_EnvGetSessionProperties(env, keys) env.GetSessionProperties(keys)
GalSS_EnvModifyServerProperties(env, properties_to_set, properties_to_delete) env.ModifyServerProperties(properties_to_set, properties_to_delete)
GalSS_EnvModifySessionProperties(env, properties_to_set, properties_to_delete) env.ModifySessionProperties(properties_to_set, properties_to_delete)
GalSS_EnvSetServerProperties(env, properties) env.ModifyServerProperties(properties_to_set = properties)
GalSS_EnvSetSession(env, session_name, lock_info) env.SetSession(session_name, lock_info)
GalSS_EnvSetSessionProperties(env, properties) env.ModifySessionProperties(properties_to_set = properties)
 
Special Main Loops The basic Python main loop works differently than the C main loop, so customizing it and embedding it works differently as well. Most of these functions don't make any sense in Python.
 
GalIO_BrokerDataInCallbackHandler(b, read_blocking) [not implemented]
GalIO_BrokerDataOutCallbackHandler(b) [not implemented]
GalIO_BrokerReadReady(b) [implemented but not visible] 
GalIO_BrokerWriteReady(b) [implemented but not visible]
GalIO_CommReadReady(gcomm) [implemented but not visible]
GalIO_CommWriteReady(gcomm) [implemented but not visible]
GalIO_ConnectionCallbackHandler(gcomm, read_blocking) [not implemented]
GalIO_DigestServerLocations(client_pair_string) [not implemented]
GalIO_GetServerLocations(scomm) [not implemented]
GalIO_NthHostAndPort(locs, i, port) [not implemented]
GalIO_NumServerLocations(locs) [not implemented]
GalIO_ServerCallbackHandler(scomm, read_blocking, new_conn_ptr) [not implemented]
GalIO_ServerCheckHubContacts(scomm) [not implemented]
GalSS_ELRBroker(elr) [not implemented]
GalSS_ELRCopy(source) [not implemented]
GalSS_ELRCreate(scomm, timer_set_fn, timer_unset_fn, fd_set_fn, fd_unset_fn, behavior_fn, timer_is_persistent) [not implemented]
GalSS_ELRDestroy(elr) [not implemented]
GalSS_ELRDoCallback(elr, timer_or_fd) [not implemented]
GalSS_ELRGComm(elr) [not implemented]
GalSS_ELRGetLoopData(elr) [not implemented]
GalSS_ELRSComm(elr) [not implemented]
GalSS_ELRSetBrokerInCallback(elr, fn) [not implemented]
GalSS_ELRSetBrokerOutCallback(elr, fn) [not implemented]
GalSS_ELRSetConnectionCallback(elr, fn) [not implemented]
GalSS_ELRSetLoopData(elr, loop_data, loop_data_free_fn ) [not implemented]
GalSS_ELRSetServerClientCallback(elr, fn) [not implemented]
GalSS_ELRSetServerListenerCallback(elr, fn) [not implemented]
GalSS_ELRSetupServer(external_arg_pkg, argc, argv, timer_set_fn, timer_unset_fn, fd_set_fn, fd_unset_fn, behavior_fn, loop_data, loop_data_free_fn , timer_is_persistent) [not implemented]
GalSS_ELRShutdown(elr) [not implemented]
GalSS_ELRUpdatePollIntervals(elr, server_client_poll_ms, conn_ms, broker_ms) [not implemented]
 
Signal Handling  
 
Gal_AddSignalHandler(sig, handler ) [not implemented]
Gal_InitializeSignals() [not implemented]
Gal_SignalsInitialized() [not implemented]
 
Command Line Argument Parsing and Printing Utilities Streams for printout are attached to call environments and connections in Python.
 
GalUtil_Assert(truth, format, ...) env.ostream.p_assert(truth, msg)
GalUtil_CPInfo1(fore, back, format, ...) [not implemented]
GalUtil_CPInfo2(fore, back, format, ...) [not implemented]
GalUtil_CPrint(level, fore, back, format, ...) [not implemented]
GalUtil_Debug1(format, ...) env.ostream.debug1(msg)
GalUtil_Debug2(format, ...) env.ostream.debug2(msg)
GalUtil_Error(format, ...) env.ostream.error(msg)
GalUtil_Fatal(format, ...) env.ostream.fatal(msg)
GalUtil_OACheckUsage(argc, argv, oas, first_real_arg) GalaxyIO.Server.CheckUsage(scomm, oas, argv)
GalUtil_OAExtract(argc, argv, oas, key, ...) SLSUtil.OAExtract(oas, argv, ostream)
GalUtil_OAExtractAsserting(argc, argv, oas, key, ...) [not implemented]
GalUtil_OAPrintUsage(argc, argv, oas) SLSUtil.OAPrintUsage(oas)
GalUtil_PInfo1(format, ...) env.ostream.pinfo1(msg)
GalUtil_PInfo2(format, ...) env.ostream.pinfo2(msg)
GalUtil_Print(level, format, ...) env.ostream.write_level(level, msg)
GalUtil_SetVerbose(verbose_level) env.ostream.set_verbosity(verbose_level)
GalUtil_VerboseUseBW() [not implemented]
GalUtil_VerboseUseColor() [not implemented]
GalUtil_Warn(format, ...) env.ostream.warn(msg)
 
How to Use the Communicator Library in Arbitrary Executables  
 
GalIO_ClientConnect(name, host, port, silent, welcome_frame, reply_frame) GalaxyIO.ClientConnection(host, port, welcome_frame) 
Gal_InitializeStatics() [not needed; called when the bindings are loaded]


Please send comments and suggestions to: bugs-darpacomm@linus.mitre.org
Last updated October 25, 2001.

Copyright (c) 1998 - 2001
The MITRE Corporation
ALL RIGHTS RESERVED