Buffer Passing

This document describes buffer passing between objects.

There are two models for passing buffers between objects:

The Push-Accept model of buffer passing is used when one object "pushes" data to another object by calling the receiving object's "accept" command and providing a scatter buffer list as input. In this model, the initiating object (i.e., the pusher), generally has the configuration slots "-outCmd", "-cycleTime", and "-lts". The exact name of these configuration slots is object type dependent but these three are used most by convention. The "-outCmd" slot simply specifies a command to be called when data needs to be sent. The command is appended with a scatter buffer list as an argument. The "-cycleTime" slot specifies how often the command is executed (i.e., once every cycleTime seconds). The "-lts" slot is used to indicate which lts object is to be used to control timing.

The Pull-Send model of buffer passing is used when one object "pulls" data out of another object by calling the sending object's "send" command. In this model, the initaiting object (i.e., hte puller) generally has the configuration slots "-inCmd", "-cycleTime", and "-lts". Once again, the exact names for these slots is object type dependent but these are used most by convention. The "-inCmd" specifies a command to be called when data is needed. The command should produce a scatter buffer list. The "-cycleTime" and "-lts" slots are used to control timing of when the command is executed.

Because pushing and sending data occurs so often, we would like to avoid the Tcl overhead associated with executing Tcl commands. To this end, a convention for registering a C procedure that will produce or accept a C representation of the scatterbuffer list is available. If an object has a "send" or "accept" command and would also like to register a C interface to this command, the object does so by registering the atom <object_name>.accept or <object_name>.send with the CM atom registration module. The data associated with this atom should be a pointer to the function in question. The exact name of the atom registered does not have to use ".accept" or ".send" as the suffix, but these suffixes are used most by convention. The atom name does, however, have to be in the form <object_name>.<token> where <token> is a string that can not contain a ".". The prototype of the C function of send and accept commands must match the prototypes in cmBufferlist.h.

On the other end of things, if the value of "-inCmd" or "-outCmd" begins with a "@", a pushing or pulling object should interpret the value of these configuration slots as registered C procedure atoms. The pushing or pulling object should look up the atom (i.e., everything beyond the "@") in order to find the pointer to the function in question.

The function prototypes for a C interface to sending or accepting scatter buffer lists both require a pointer to the C data structure of the sending or accepting object as their first argument. To this end, the pushing or pulling object should parse the sending or accepting object name from the atom name by stripping off the suffix (i.e., everything in the atom name after the last "." including the "." itself). Using Tcl_CommandInfo, the pushing or pulling object can look up the pointer to the sending or accepting object by looking up the sending or accepting object's name as a Tcl command and utilizing the Clientdata pointer in the command info structure.

The second argument to the C interface of the sending or accepting procedure depends on whether the function is sending or accepting data. Accepting functions require a SB_List pointer that points to the data to be sent. Sending functions require a pointer to a SB_List pointer. This pointer will be set to a SB_List pointer that points to the data being sent.

For a description of scatterbuffer lists, their Tcl and C representations, and the format of data stored inside them, go to this link.