Galaxy Communicator Documentation:

MITRE Allegro Common Lisp Bindings


We have prepared a (crude) set of Communicator bindings for Common Lisp. We do not provide as much support as we do for Python at the moment. There are fewer demos, and there is no support for MITRE utilities equivalents yet. These bindings are specific to Allegro Common Lisp, since the Common Lisp language has no official networking support and we have no experience with other Common Lisp dialects.


Enabling Allegro bindings

See the installation documentation for how to enable the Allegro bindings. Allegro 5.0 or later is required.


Documentation Summary

The bindings are divided into files which correspond approximately to subdirectories of libGalaxy: Galaxy.cl (galaxy), GalaxyIO.cl (io, ServerStub), and SLSUtil.cl (util). MGalaxy.cl (MITRE's libMITREgalaxy) is currently not implemented. There are two other files, cGalaxy.cl and acl_callbacks.c, which provided wrappers around the core Galaxy Communicator C library.

The following demos contain Allegro Common Lisp server examples. All examples can be found in the acl/ subdirectory of these demos:

The Allegro 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 Allegro bindings as to the core C library. We address the important differences here.

Introducing frames and objects

In general, because Allegro is a dynamically typed language and supports association lists 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 Allegro. Note that the data in the frame is stored as an association list.
;; {c output :output_string "hello" }

(setf f (make-instance 'galaxy::gal-clause-frame :name "output"))
(set-prop f ":output_string" "hello")

;; or

(setf f (make-instance 'galaxy::gal-clause-frame :name "output"
                       :data '((":output_string" . "hello"))))

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

(setf f (make-instance 'galaxy::gal-clause-frame :name "listframe"))
(set-prop f ":list" (list 5 6 7))

;; or

(setf f (make-instance 'galaxy::gal-clause-frame :name "listframe"
                       :data '((":list" . (5 6 7)))))

Server basics

In order to access the Allegro bindings, we use a fairly complicated set of instructions which loads the shared object library and the native Allegro code built on top of the library, and configures the read-eval-print loop for silent operation. The location of the libraries is specified by the LIBDIR environment variable. This initialization file is located at $GC_HOME/contrib/MITRE/templates/acl-init.cl. We load this file as we start up Allegro, as follows:
% setenv LIBDIR $GC_HOME/contrib/MITRE/bindings/clisp
% acl -qq -batch -backtrack-on-error -e '(setf lisp:*load-verbose* nil)' -e '(load "$GC_HOME/contrib/MITRE/templates/acl-init.cl") -- [cmdline_args] < [server_code_file]
There are almost certainly less cumbersome ways of doing this, but they'll probably involve having more verbose printing at startup than you're interested in.

Each dispatch function takes an environment object and a frame and returns a frame. In the case of Allegro, the call environment is the first argument, so that methods on classes inherited from galaxy-io::call-environment also have the same signature.

Here's an Allegro equivalent of the Parse dispatch function:

(defun Parse (env frame)
  (let* ((input-string (galaxy::get-object frame ":input_string"))
         (p (parse-sentence input-string)))
    (make-instance 'galaxy::gal-clause-frame :name "reply"
                   :data `((":frame" . ,(parse-tree-to-frame p))))))
Allegro 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:
(setf s (make-instance 'galaxy-io::server
                       :name "Parser"
                       :argv (sys:command-line-arguments :application t)
                       :default-port 10000))
(galaxy-io::add-dispatch-function s "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:

(defclass parse-environment (galaxy-io::call-environment) ())

(defmethod Parse ((env parse-environment) frame)
  (let* ((input-string (galaxy::get-object frame ":input_string"))
         (p (parse-sentence input-string)))
    (make-instance 'galaxy::gal-clause-frame :name "reply"
                   :data `((":frame" . ,(parse-tree-to-frame p))))))

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

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

The Allegro bindings have no functionality equivalent to the core C argument parsing library.

Error handling

Unlike C, Allegro has explicit errors, and handlers for catching them. If you raise an error in a dispatch function (intentionally or otherwise), the Allegro bindings will catch the error and convert it to an error reply. Here's the Parse function again:
(defun Parse (env frame)
  (let ((input-string (galaxy::get-object frame ":input_string"))
        (p nil)
        (p-frame nil))
    (if (not (stringp input-string))
        (error "no input string"))
    (setf p (parse-sentence input-string))
    (if (null p)
        (error "no parse"))
    (setf p-frame (parse-tree-to-frame p))
    (if (null p-frame)
        (error "can't convert parse to frame"))
    (make-instance 'galaxy::gal-clause-frame :name "reply"
                   :data `((":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:
(defun DoGreeting (env frame)
  (let* ((s "{c FromDialogue :output_frame {c greeting } :is_greeting 1 }")
         (greeting (galaxy::read-frame-from-string s)))
    (galaxy-io::write-frame env greeting)
    nil))
If you want to return no frame to the Hub, you must return nil; if the last expression evaluated in the function is not nil, it will be treated as the reply.

Now, here's the DoDialogue example:

(defun DoDialogue (env frame)
  (let ((msg-frame (make-instance 'galaxy::gal-clause-frame :name "DBQuery"))
        (response-frame nil))
 
    ;; ...

    (galaxy::set-prop msg-frame ":sql_query" sql_query)

    (handler-case
        (let ((response-frame
                (galaxy-io::dispatch-frame env msg-frame)))
          ;; Equivalent of GAL_REPLY_MSG_TYPE.
          ;; Construct presentation of database response
          ;; ...
          )
      (galaxy-io::dispatch-error (e)
        ;; Equivalent of GAL_ERROR_MSG_TYPE
        ;; Relay error back to Hub
        ;; ...
        ))))

If the Hub relays an error back to the server, the Allegro bindings will raise the error locally. The error raised will be galaxy-io::dispatch-error, as shown here.

Setting up a brokered audio connection

In order to set up a broker server, you can use the class galaxy-io::broker-data-out directly, most of the time. For the broker client, you should subclass galaxy-io::broker-data-in. The methods galaxy-io::env-handle-frame, galaxy-io::env-handle-string, galaxy-io::env-handle-binary, galaxy-io::env-handle-int-16, etc., can be redefined on the subclassed broker client to handle the appropriate class of incoming data. Outgoing data is handled using the galaxy-io::write-object 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:

(defun Synthesize (env frame)
  ;; ...
  (handler-case
      (let ((b (make-instance 'galaxy-io::broker-data-out
                              :connection (galaxy-io::env-connection env)
                              :timeout 10))
            (output-f (make-instance 'galaxy::gal-clause-frame
                                     :name "FromSynthesizer"
                                     :data `((":sample_rate" . ,(sample-rate s))
                                             (":encoding_format" . ,(encoding-format s))))))
        (galaxy-io::populate-frame b output-f ":host" "port")
        (galaxy-io::write-frame env output-f))
    (galaxy-io::broker-connected (e)
      ;; ...
      )))
Now, here's the setup for the client:
(defclass audio-broker (galaxy-io::broker-data-in) ())

;; ...

(defun Play (env frame)
  (let ((host (galaxy::get-object frame ":host"))
        (port (galaxy::get-object frame ":port"))
        (p (make-instance 'audio-pkg)))

    ;; ...

    (handler-case
        (progn
          (setf (in-broker p) (make-instance 'audio-broker
                                             :environment env
                                             :host host :port port))
          (galaxy-io::add-callback (in-broker p) galaxy-io::*GAL-BROKER-DATA-DONE-EVENT*
                                   #'(lambda () (audio-output-callback (in-broker p))))
          ;; ...
          )
      (galaxy-io::broker-connected (e)
        ;; ...
        ))))

The data exchange works as follows. First, on the source server:
(do ((data (poll-synthesis s) (poll-synthesis s)))
    ((null data))
  (galaxy-io::write-object b data))

(if (synthesis-is-done s)
    (galaxy-io::data-done b))

On the client, it's handled as methods associated with the specialized broker class:
(defmethod galaxy-io::env-handle-int-16 ((b audio-broker) env obj)
  (format t "[Audio data to user (~d samples)]~%" (length obj)))
Unhandled data types raise galaxy-io::broker-data-not-handled.


Known Bugs


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, to) [not implemented]
GalUtil_PPFrame(verbose_level, fr) (sls-util::gal-write-level ostream (galaxy::pp-frame fr nil) verbose_level)
GalUtil_PPObject(verbose_level, o) (sls-util::gal-write-level ostream (galaxy::pr-object o nil :pp) verbose_level)
GalUtil_PrObject(verbose_level, o) (sls-util::gal-write-level ostream (galaxy::pr-object o nil) verbose_level)
GalUtil_PrintObject(gverbose_level, o, how)  (sls-util::gal-write-level ostream (galaxy::pr-object o nil how) verbose_level)
Gal_AddPred(fr, pred) (push pred (galaxy::frame-preds fr))
Gal_ArrayObjectAdd(obj, data, size) (galaxy::augment-binary-object obj data)
Gal_BinaryObject(data, size) (galaxy::binary-object 'galaxy::gal-binary :data data)
Gal_BinarySize(o) (length o)
Gal_BinaryValue(obj, size) (galaxy::value-warn obj 'galaxy::gal-binary)
Gal_Binaryp(obj) (typep obj 'galaxy::gal-binary)
Gal_ClauseFramep(fr) (typep fr 'galaxy::gal-clause-frame)
Gal_ClauseValue(o) (galaxy::value-warn o 'galaxy::gal-clause-frame)
Gal_Clausep(obj) (typep obj 'galaxy::gal-clause-frame)
Gal_ClearPreds(fr) (setf (galaxy::frame-preds fr) nil)
Gal_CopyFrame(fr) [not implemented]
Gal_CopyObject(obj) [not implemented]
Gal_CreateBinaryObject(data, size, manage_memory) (galaxy::binary-object 'galaxy::gal-binary :data data)
Gal_CreateFloat32Object(data, num_float_32, manage_memory) (galaxy::binary-object 'galaxy::gal-float-32 :data data)
Gal_CreateFloat64Object(data, num_float_64, manage_memory) (galaxy::binary-object 'galaxy::gal-float-64 :data data)
Gal_CreateFloatObject(value, manage_memory) [not needed]
Gal_CreateFrameObject(value, manage_memory) [not needed]
Gal_CreateInt16Object(data, num_int_16, manage_memory) (galaxy::binary-object 'galaxy::gal-int-16 :data data)
Gal_CreateInt32Object(data, num_int_32, manage_memory) (galaxy::binary-object 'galaxy::gal-int-32 :data data)
Gal_CreateInt64Object(data, num_int_64, manage_memory) [not implemented]
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) (galaxy::rem-pred fr i)
Gal_DelPredByName(fr, name) (galaxy::rem-pred-by-name fr name)
Gal_DelProp(fr, key) (galaxy::del-prop fr key)
Gal_DeletePreds(fr, pred_name) [not implemented]
Gal_DoPreds(fr, pred_fn , caller_data) (mapcar pred_fn (galaxy::frame-preds fr))
Gal_DoProperties(fr, prop_fn , caller_data) (mapcar prop_fn (galaxy::frame-data fr))
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) (length o)
Gal_Float32Value(obj, size) (galaxy::value-warn obj 'galaxy::gal-float-32)
Gal_Float32p(o) (typep o 'galaxy::gal-float-32)
Gal_Float64Size(o) (length o)
Gal_Float64Value(obj, size) (galaxy::value-warn obj 'galaxy::gal-float-64)
Gal_Float64p(o) (typep o 'galaxy::gal-float-64)
Gal_FloatObject(val) [not needed]
Gal_FloatValue(to) (galaxy::value-warn obj 'galaxy::gal-float)
Gal_Floatp(obj) (typep obj 'galaxy::gal-float)
Gal_FrameEqual(sf1, sf2) [not implemented[
Gal_FrameIsType(fr, type) (eq (galaxy::frame-type fr) type)
Gal_FrameName(fr) (galaxy::frame-name fr)
Gal_FrameNameEq(fr, name) (string= (galaxy::frame-name fr) name)
Gal_FrameNamesEq(fr1, fr2) (string= (galaxy::frame-name fr1) (galaxy::frame-name fr2))
Gal_FrameObject(val) [not needed]
Gal_FrameValue(to) (galaxy::value-warn obj 'galaxy::gal-frame)
Gal_Framep(obj) (typep obj 'galaxy::gal-frame)
Gal_FreeFrame(fr) [not needed]
Gal_FreeObject(obj) [not needed]
Gal_FreeWrapper(to) [not needed]
Gal_GetBinary(fr, key, size) (galaxy::get-value fr key 'galaxy::gal-binary)
Gal_GetDetailedType(o) (galaxy::get-detailed-type o)
Gal_GetFloat(fr, key) (galaxy::get-value fr key 'galaxy::gal-float)
Gal_GetFloat32(fr, key, size) (galaxy::get-value fr key 'galaxy::gal-float-32)
Gal_GetFloat64(fr, key, size) (galaxy::get-value fr key 'galaxy::gal-float-64)
Gal_GetFrame(fr, key) (galaxy::get-value fr key 'galaxy::gal-frame)
Gal_GetFrameType(fr) (galaxy::frame-type fr)
Gal_GetInt(fr, key) (galaxy::get-value fr key 'galaxy::gal-int)
Gal_GetInt16(fr, key, size) (galaxy::get-value fr key 'galaxy::gal-int-16)
Gal_GetInt32(fr, key, size) (galaxy::get-value fr key 'galaxy::gal-int-32)
Gal_GetInt64(fr, key, size) [not implemented]
Gal_GetList(fr, key, length) (galaxy::get-value fr key 'galaxy::gal-list)
Gal_GetListObject(obj, n) (elt obj n)
Gal_GetListValue(o, n, type) (galaxy::value-warn (elt o n) type)
Gal_GetObject(fr, key) (galaxy::get-object fr key)
Gal_GetObjectType(o) (galaxy::get-object-type o)
Gal_GetObjectTypeString(o) (galaxy::object-type-string (galaxy::get-object-type o))
Gal_GetPred(fr, i) (elt (galaxy::frame-preds fr) i)
Gal_GetPredByName(fr, name) (galaxy::get-pred-by-name fr name)
Gal_GetProperties(fr, nkeys) (galaxy::gal-get-properties fr) [get-properties is a CL internal function]
Gal_GetString(fr, key) (galaxy::get-value fr key 'galaxy::gal-string)
Gal_GetTopicFrame(fr, key) (galaxy::get-value fr key 'galaxy::gal-topic-frame)
Gal_Int16Size(o) (length o)
Gal_Int16Value(obj, size) (galaxy::value-warn obj 'galaxy::gal-int-16)
Gal_Int16p(o) (typep o 'galaxy::gal-int-16)
Gal_Int32Size(o) (length o)
Gal_Int32Value(obj, size) (galaxy::value-warn obj 'galaxy::gal-int-32)
Gal_Int32p(o) (typep o 'galaxy::gal-int-32)
Gal_Int64Size(to) [not implemented]
Gal_Int64Value(obj, size) [not implemented]
Gal_Int64p(to) [not implemented]
Gal_IntObject(val) [not needed]
Gal_IntValue(o) (galaxy::value-warn o 'galaxy::gal-int)
Gal_Intp(obj) (typep obj 'galaxy::gal-int)
Gal_ListLength(obj) (length obj)
Gal_ListObject(values, n) [not needed]
Gal_ListObjectAdd(obj, elt) (nconc obj (list elt))
Gal_ListObjectFromElements(n, ...) [not needed]
Gal_ListValue(obj, n) (galaxy::value-warn obj 'galaxy::gal-list)
Gal_Listp(obj) (typep obj 'galaxy::gal-list)
Gal_MakeClauseFrame(name) (make-instance 'galaxy::gal-clause-frame :name name)
Gal_MakeFrame(name, type) (make-instance 'galaxy::gal-topic-frame :name name) OR (make-instance 'galaxy::gal-clause-frame :name name) OR (make-instance 'galaxy::gal-pred-frame :name name)
Gal_MakePredFrame(name) (make-instance 'galaxy::gal-pred-frame :name name)
Gal_MakeTopicFrame(name) (make-instance 'galaxy::gal-topic-frame :name name)
Gal_MatchFrame(sf1, sf2) [not implemented]
Gal_MatchKeyValue(fr, key_name, match) [not implemented]
Gal_NumNonNullProperties(fr) (galaxy::num-properties fr)
Gal_NumPreds(fr) (length (galaxy::frame-preds fr))
Gal_NumProperties(fr) (galaxy::num-properties fr)
Gal_ObjectByteCount(obj) [not implemented]
Gal_ObjectCaseEqual(obj1, obj2) [not implemented]
Gal_ObjectEqual(obj1, obj2) [not implemented]
Gal_ObjectToString(o) (galaxy::pr-object o nil)
Gal_ObjectTypeString(object_type) (galaxy::object-type-string object_type)
Gal_OutlineFrame(fr, sls_verbose_level) [not implemented]
Gal_OutlineObject(to, sls_verbose_level) [not implemented]
Gal_PPFrame(fr) (galaxy::pp-frame fr T)
Gal_PPFrameToFile(fr, fp) (galaxy::pp-frame fr fp)
Gal_PPFrameToString(fr, buf, bufsizeptr) (galaxy::pp-frame fr nil)
Gal_PPObject(o) (galaxy::pr-object o T galaxy::*GAL-PR-PRINT*)
Gal_PPObjectToFile(o, fp) (galaxy::pr-object o fp galaxy::*GAL-PP-PRINT*)
Gal_PrFrame(fr) (galaxy::pr-frame fr T)
Gal_PrFrameToFile(fr, fp) (galaxy::pr-frame fr fp)
Gal_PrFrameToString(fr, buf, bufsizeptr) (galaxy::pr-frame f nil)
Gal_PrObject(obj) (galaxy::pr-object obj T)
Gal_PrObjectToFile(obj, fp) (galaxy::pr-object obj fp)
Gal_PredFramep(fr) (typep fr 'galaxy::gal-pred-frame)
Gal_PredValue(o) (galaxy::value-warn obj 'galaxy::gal-pred-frame)
Gal_Predp(obj) (typep obj 'galaxy::gal-pred-frame)
Gal_PrintFrameToFile(fr, fp, how) (galaxy::print-frame fr fp how)
Gal_PrintFrameToString(fr, irpbuf, bufsizeptr, how) (galaxy::print-frame fr nil how)
Gal_ReadFrameFromFile(fp) [not implemented]
Gal_ReadFrameFromString(buf) (galaxy::read-frame-from-string buf)
Gal_ReadObjectFromFile(fp) [not implemented]
Gal_ReadObjectFromString(buf) (galaxy::read-irp-value buf) (approximately)
Gal_ReadVarFrameFromString(buf, map) [not implemented]
Gal_RemPred(fr, i) (galaxy::rem-pred fr i)
Gal_RemPredByName(fr, name) (galaxy::rem-pred-by-name fr name)
Gal_RemProp(fr, key) (talaxy::rem-prop fr key)
Gal_SetFrameName(fr, name) (setf (galaxy::frame-name fr) name)
Gal_SetFrameType(fr, type) (setf (galaxy::frame-type fr) type)
Gal_SetProp(fr, key, obj) (galaxy::set-prop fr key obj)
Gal_StringObject(val) [not needed]
Gal_StringValue(to) (galaxy::value-warn obj 'galaxy::gal-string)
Gal_Stringp(obj) (typep obj 'galaxy::gal-string)
Gal_TopicFramep(fr) (typep obj 'galaxy::gal-topic-frame)
Gal_TopicValue(to) [not implemented]
Gal_Topicp(obj) (typep obj 'galaxy::gal-topic-frame)
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; catch galaxy-io::dispatch-error]
GalSS_AddDispatchFunction(i, name, fn, in_key_array, allow_other_in_keys, reply_provided, out_key_array, allow_other_out_keys) (galaxy-io::add-dispatch-function ...)
GalSS_EnvDestroyToken(env) (galaxy-io::destroy-token env)
GalSS_EnvDispatchFrame(env, frame, t) (galaxy-io::dispatch-frame env frame)
GalSS_EnvError(env, description) [not needed; just raise error]
GalSS_EnvGetClientData(env, name) [not needed; specialize class and add instance variable]
GalSS_EnvGetCommData(env) [not needed; specialize class and add instance variable]
GalSS_EnvReply(env, f) (galaxy-io::reply env f)
GalSS_EnvSetCommData(env, data, free_fn ) [not needed; specialize class and add instance variable]
GalSS_EnvWriteFrame(env, frame, do_block) (galaxy::write-frame env 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]
_GalSS_print_usage(argc, argv) [not implemented]
 
Brokering and Audio Data  
 
GalIO_BrokerDataDone(b) (galaxy-io::data-done b)
GalIO_BrokerDataInInit(host, port, frame, fnptr, caller_data, poll_ms) [not implemented]
GalIO_BrokerDataOutDone(b) (galaxy-io::data-done b)
GalIO_BrokerDataOutInit(gcomm, poll_ms, timeout_seconds) (make-instance 'galaxy-io::broker-data-out :connection gcomm :timeout timeout_seconds)
GalIO_BrokerIsDone(b) [not implemented]
GalIO_BrokerPopulateFrame(b, f, host_key, port_key) (galaxy-io::populate-frame b f host_key port_key)
GalIO_BrokerSetFinalizer(b, finalizer) [not implemented]
GalIO_BrokerStructDequeue(b, bqueue) [not needed; no broker queues in Allegro]
GalIO_BrokerStructQueueAppend(b, bqueue) [not needed; no broker queues in Allegro]
GalIO_BrokerStructQueuePop(bqueue) [not needed; no broker queues in Allegro]
GalIO_BrokerWriteBinary(b, data, n_bytes) (galaxy-io::write-object b data)
GalIO_BrokerWriteFloat(b, f) (galaxy-io::write-object b f)
GalIO_BrokerWriteFloat32(b, data, n_floats) (galaxy-io::write-object b data)
GalIO_BrokerWriteFloat64(b, data, n_floats) (galaxy-io::write-object b data)
GalIO_BrokerWriteFrame(b, frame) (galaxy-io::write-object b f)
GalIO_BrokerWriteInt(b, i) (galaxy-io::write-object b i)
GalIO_BrokerWriteInt16(b, data, n_ints) (galaxy-io::write-object b data)
GalIO_BrokerWriteInt32(b, data, n_ints) (galaxy-io::write-object b data)
GalIO_BrokerWriteInt64(b, data, n_ints) (galaxy-io::write-object b data)
GalIO_BrokerWriteList(b, elts, n_elts) (galaxy-io::write-object b data)
GalIO_BrokerWriteObject(b, o) (galaxy-io::write-object b o)
GalIO_BrokerWriteString(b, str) (galaxy-io::write-object b str)
GalIO_CommBrokerDataInInit(host_gcomm, host, port, frame, fnptr, poll_ms, caller_data, caller_data_free_fn ) (make-instance 'galaxy-io::broker-data-in :host host :port port :frame frame :connection host_gcomm)
GalIO_ForceBrokerExpiration(b) [not implemented]
GalIO_FrameSetBrokerCallID(f, call_id) [not implemented]
GalIO_GetBrokerCallID(b) (galaxy-io::broker-data-out-call-id b)
GalIO_GetBrokerCallerData(b) [not needed; use child class]
GalIO_GetBrokerData(b) [not needed; use child class]
GalIO_GetBrokerFrame(b) [not implemented]
GalIO_GetBrokerListenPort(b) (galaxy-io::broker-data-out-port b)
GalIO_IPAddress() (galaxy-io::ip-address)
GalIO_SetBrokerActive(b) [not needed; no broker queues in Allegro]
GalIO_SetBrokerData(b, caller_data, free_fn ) [not needed; use child class]
GalSS_BrokerGetEnvironment(b) (galaxy-io::broker-data-in-environment b)
GalSS_BrokerSetEnvironment(b, env) [not needed; initialize in broker with environment]
GalSS_EnvBrokerDataInInit(env, host, port, frame, fnptr, poll_ms, refptr, free_fn ) (make-instance 'galaxy-io::broker-data-in :host host :port port :frame frame :environment env)
 
Server Architecture  
 
GalIO_AddBrokerCallback(b, callback_event, fn, callback_data) (galaxy-io::add-callback b callback_event fn)
GalIO_AddConnectionBrokerCallback(gcomm, callback_event, connect_callback, callback_data) [not needed; specialize initialization methods]
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) (galaxy-io::server-validate (galaxy-io::connection-server gcomm))
GalIO_CommWriteFrame(gcomm, frame, do_block) (galaxy-io::write-frame gcomm frame)
GalIO_ContactHub(host, port, scomm, session_id, client_poll_flags) [not implemented]
GalIO_DispatchViaHub(gcomm, frame, msg_type_ptr) (galaxy-io::dispatch-frame gcomm frame)
GalIO_EnableDispatchFnValidation(scomm) (setf (galaxy-io::server-validate s) t)
GalIO_GetCommClientData(gcomm, name) [not needed; use child class]
GalIO_GetCommData(gcomm) [not needed; use child class]
GalIO_GetCommServerData(gcomm) [not needed; use child class]
GalIO_GetCommServerName(gcomm) (galaxy-io::server-name (galaxy-io::connection-server gcomm))
GalIO_GetServerClientData(server, name) [not needed; use child class]
GalIO_GetServerData(scomm) [not needed; use child class]
GalIO_GetServerDefaultPort(scomm) (galaxy-io::server-default-port scomm)
GalIO_GetServerListenPort(scomm) (galaxy-io::server-port scomm)
GalIO_GetServerMaxConnections(scomm) (galaxy-io::server-maxconns scomm)
GalIO_GetServerName(scomm) (galaxy-io::server-name scomm)
GalIO_GetServerNumConnections(scomm) (length (galaxy-io::server-conns scomm))
GalIO_GetUniqueConnection(scomm) [not implemented]
GalIO_OperateOnConnections(scomm, arg, op ) (mapcar #'(lambda (a) (op (cdr a)) (galaxy-io::server-conns scomm))
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 child class]
GalIO_SetCommData(gcomm, data, free_fn ) [not needed; use child class]
GalIO_SetServerClientData(server, name, client_data) [not needed; use child class]
GalIO_SetServerData(scomm, data, free_fn ) [not needed; use child class]
GalIO_SetServerDefaultPort(scomm, port) (setf (galaxy-io::server-default-port scomm) port)
GalIO_SetServerMaxConnections(scomm, max) (setf (galaxy-io::server-maxconns scomm) max)
GalIO_SetServerName(scomm, name) (setf (galaxy-io::server-name scomm) name)
GalSS_CmdlineInitializeServer(argc, argv) [not implemented]
GalSS_CmdlineSetupServer(argc, argv) [not implemented]
GalSS_DefaultServerArgs() [not implemented]
GalSS_EnvComm(env) (galaxy-io::env-connection c)
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) (make-instance 'galaxy-io::server ... )
GalSS_InitializeServerFromServerArgs(arg_pkg, new_argc, new_argv) (make-instance 'galaxy-io::server ... )
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) (make-instance 'galaxy-io::server ... )
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) (make-instance 'galaxy-io::server ... )
GalSS_StartAndRunServer(server) (galaxy-io::run-server s)
 
The Timed Task Loop
None of these functions are implemtened, because Allegro 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) (make-instance 'galaxy-io::call-environment :connection gcomm)
GalSS_EnvDispatchFrameWithContinuation(env, frame, fn, continuation_state, continuation_state_free_fn ) (galaxy-io::dispatch-frame-with-continuation env frame fn)
GalSS_EnvGetSessionID(env) (galaxy-io::get-session-id env)
GalSS_EnvLock(env) [not needed]
GalSS_EnvMaintainInLocation(gcomm, initial_session_id, env_loc) [not implemented]
GalSS_EnvPostponeReply(env) [not implemented]
GalSS_EnvReturnRequired(env) [not implemented]
GalSS_EnvUnlock(env) [not needed]
GalSS_EnvUpdateSessionID(env, session_id) (galaxy-io::update-session-id env 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) (galaxy-io::add-service-type server stype)
GalIO_ServerModifyProperties(server, new_properties, delete_properties) (galaxy-io::modify-properties server :properties-to-set new_properties :properties-to-delete delete_properties)
GalIO_ServerProperties(server) [not implemented]
GalSS_EnvDeleteServerProperties(env, keys) (galaxy-io::modify-server-properties env :properties-to-delete keys)
GalSS_EnvDeleteSessionProperties(env, keys) (galaxy-io::modify-session-properties env :properties-to-delete keys)
GalSS_EnvGetServerProperties(env, keys) (galaxy-io::get-server-properties env keys)
GalSS_EnvGetSessionProperties(env, keys) (galaxy-io::get-session-properties env keys)
GalSS_EnvModifyServerProperties(env, properties_to_set, properties_to_delete) (galaxy-io::modify-server-properties :properties-to-set properties_to_set :properties-to-delete properties_to_delete)
GalSS_EnvModifySessionProperties(env, properties_to_set, properties_to_delete) (galaxy-io::modify-session-properties :properties-to-set properties_to_set :properties-to-delete properties_to_delete)
GalSS_EnvSetServerProperties(env, properties) (galaxy-io::modify-server-properties :properties-to-set properties_to_set)
GalSS_EnvSetSession(env, session_name, lock_info) (galaxy-io::set-session env session_name lock_info)
GalSS_EnvSetSessionProperties(env, properties) (galaxy-io::modify-session-properties :properties-to-set properties_to_set)
 
Special Main Loops The basic Allegro 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 Allegro.
 
GalIO_BrokerDataInCallbackHandler(b, read_blocking) [not implemented]
GalIO_BrokerDataOutCallbackHandler(b) [not implemented]
GalIO_BrokerReadReady(b) [not implemented]
GalIO_BrokerWriteReady(b) [not implemented]
GalIO_CommReadReady(gcomm) [not implemented]
GalIO_CommWriteReady(gcomm) [not implemented]
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  
 
GalUtil_Assert(truth, format, ...) (sls-util::gal-assert (galaxy-io::ostream conn) 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, ...) (sls-util::debug1 (galaxy-io::ostream conn) msg)
GalUtil_Debug2(format, ...) (sls-util::debug2 (galaxy-io::ostream conn) msg)
GalUtil_Error(format, ...) (sls-util::gal-error (galaxy-io::ostream conn) msg)
GalUtil_Fatal(format, ...) (sls-util::fatal (galaxy-io::ostream conn) msg)
GalUtil_OACheckUsage(argc, argv, oas, first_real_arg) [not implemented]
GalUtil_OAExtract(argc, argv, oas, key, ...) [not implemented]
GalUtil_OAExtractAsserting(argc, argv, oas, key, ...) [not implemented]
GalUtil_OAPrintUsage(argc, argv, oas) [not implemented]
GalUtil_PInfo1(format, ...) (sls-util::pinfo1 (galaxy-io::ostream conn) msg)
GalUtil_PInfo2(format, ...) (sls-util::pinfo2 (galaxy-io::ostream conn) msg)
GalUtil_Print(level, format, ...) (sls-util::gal-write-level (galaxy-io::ostream conn) msg level)
GalUtil_SetVerbose(verbose_level) [not implemented]
GalUtil_VerboseUseBW() [not implemented]
GalUtil_VerboseUseColor() [not implemented]
GalUtil_Warn(format, ...) (sls-util::gal-warn (galaxy-io::ostream conn) msg)
 
How to Use the Communicator Library in Arbitrary Executables  
 
GalIO_ClientConnect(name, host, port, silent, welcome_frame, reply_frame) [not implemented]
Gal_InitializeStatics() [not needed; called when bindings are loaded] 


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

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