OVERVIEW OF CSL/SSL v1.0
Created: 5/22/1995
Definition of important terms and abreviations:
- CSL: Client Support Library
- SSL: Server Support Library
- Tsimmis Server: Any Tsimmis program that uses SSL such as Tsimmis
translators and Tsimmis mediators.
- Tsimmis Client: Any Tsimmis program that uses CSL such as Tsimmis
browsers and Tsimmis mediators.
CSL/SSL v1.0 is written based on the original csl/ssl libraries
written by Yannis. There are many changes in CSL/SSL v1.0 from the
original csl/ssl. CSL/SSL v1.0 is almost a complete rewrite.
However, it maintains the global structures of the original csl/ssl.
*************************
* CSL/SSL v1.0 FEATURES *
*************************
* The new libraries supports partial fetch of OEM objects.
* SSL provides buffering to support fetch one and fetch children for
those Tsimmis servers that support only full fetch.
* Asynchronous communication between SSL and CSL. Asynchronous
communication allows translator to pipeline the process of getting the
object from data source with transmission of objects to the client.
* Improved network protocol, no redundant object copying during
send or receive.
* Value of an OEM object may be binary instead of only char strings.
Using binary values, we can send/receive OEM object containing
binary image such as a gif picture.
* No limit on number of children an object can have. You can add
more children to an object at anytime.
* No limit on size or number of objects send or received.
* CSL returns OEM objects received in C data structures instead of
char string buffer.
* A few other things such as "undead" child processes and memory
problems are not in CSL/SSL 1.0.
* Source files are under source control using RCS. (This is not
really an improvement over the old csl/ssl since Kelly added
source control to old csl/ssl.)
* Supports 3 platforms, osf1 on Alpha, aix on RS6000, and ultrix on
DEC MIPS. Support for other platforms can be easily added.
* Improved project make process to support different versions of
object and binary files for different hardware platforms under the
same project directory.
* CSL/SSL v1.0 LAYOUT *
The layout for CSL/SSL v1.0 is different from the original csl/ssl.
CSL/SSL v1.0 is actually consisted of 3 libraries. The libraries are:
libtmcomm.a, libtmssl.a, and libtmcsl.a
libtmcomm.a provides supports for data types used throughout CSL/SSL
v1.0. Two major data types supported by libtmcomm.a are TM_Object and
TM_Data. libtmcomm.a also provides send and receive of these data
types through a network connection using either synchronously or
asynchronously.
Both libtmcsl.a and libtmssl.a provides additional functions on top of
libtmcomm.a. As a result, in order to use libtmcsl.a or libtmssl.a,
libtmcomm.a must be linked.
libtmcsl.a provides a set of functions to connect, query and extract
results from a Tsimmis server.
libtmssl.a provides a set of functions to set up a Tsimmis server loop
that takes in requests from a Tsimmis client and return results back
to the client.
The following two figures shows the configurations of different
Tsimmis programs that use CSL/SSL v1.0
+-----------------------+
Tsimmis | |
Translator | User Code |
| |
+-------+---------------+
| | libtmssl.a |
| +-----^---------+
| libtmcomm.a | |
+-------------|---------+
|
| network
|
+-------------|---------+
| libtmcomm.a | |
| +-----v---------+
| | libtmcsl.a |
+-------+---------------+
Tsimmis | |
Browser | User Code |
| |
+-----------------------+
Figure 1, example of a Tsimmis translator and Tsimmis browser, each
program uses two out of the three libraries in CSL/SSL v1.0.
+---------------------------------------+
| |
| User Code |
| |
+-------+---------------+---------------+
| | libtmssl.a | libtmcsl.a |
| +-------|-------+-------|-------+
| libtmcomm.a | | |
+---------------|---------------|-------+
| |
v v
To Tsimmis To Tsimmis
Server Programs Client programs
Figure 2, example of a Tsimmis mediator which uses all 3 libraries of
CSL/SSL v1.0.
+---------------------------------------+
| |
| User Code |
| |
+---------------------------------------+
| libtmcomm.a |
+---------------------------------------+
Figure 3, A Tsimmis program can choose not to use any of the functions
provided in libtmcsl.a or libtmssl.a. The program can write custom
routines to communicate with other programs using libtmcsl.a and
libtmssl.a. libtmcomm.a provides all the neccessary networking codes.
**************************
* MEMORY MANAGEMENT NOTE *
**************************
A number of functions in CSL/SSL v1.0 dynamically allocates memory and
deallocate memory. In general, each memory allocation function in
CSL/SSL v1.0 has a corresponding deallocation function. Memory
management in CSL/SSL v1.0 follows the following rule of thumb:
- CSL/SSL does NOT deallocate any memory that is not allocated
by CSL/SSL.
This rule is important to remember when developing user code that
interacts with CSL/SSL. For example, suppose a pointer in a CSL/SSL
data structure is set to point to a block of memory allocated by user
code, after calling CSL/SSL function the deallocate the CSL/SSL data
structure, the block of memory allocated by user code will NOT be
deallocated by CSL/SSL. Here is a C code segment showing the above
senario:
...
/* oem_object is allocated by CSL/SSL */
oem_object = TM_NewObject(0);
/*
* set label to point to memory location allocated outside
* CSL/SSL.
*/
oem_object->label = pointer_to_label;
/* deallocate oem_object using CSL/SSL routine */
TM_FreeObject(oem_object);
/*
* at this point, memory pointed by pointer_to_label is NOT
* deallocated
*/
printf(pointer_to_label); /* OK */
...
Conversely, if the user code receives a data structure from a CSL/SSL
function, and the same CSL/SSL function sets the pointer in the data
structure to point to another block of memory allocated during the
execution of the function, after deallocate the data structure by
another CSL/SSL function, the block of memory can NOT be assumed to
still exist. The following C code segment shows the above senario:
...
/*
* TM_FetchObj retrieves a TM_Object from the network. It
* allocates the memory needed by the object and all the values
* associated by the object such as label and type. It
* sets the pointers in TM_Object to point to the label and type.
* It returns a pointer to the allocated TM_Object in 'oem_object'.
*/
err = TM_FetchObj(conn, TM_FETCH_ONE, NULL, &oem_object, &result);
my_label = oem_object->label; /* make a copy of the label pointer */
printf(my_label); /* OK, label points to a string allocated
by TM_FetchObj */
/* deallocate oem_object using CSL/SSL routine */
TM_FreeObject(oem_object);
printf(my_label); /* !!! NOT OK !!! Since memory block pointed by
oem_object->label is allocated in automatically
in TM_FetchObj, when TM_FreeObject is called,
the memory block is also deallocated. The
saved label pointer now points to a invalid
memory block.
*/
...
*********************
* RELATED DOCUMENTS *
*********************
COMM.DOC - document on libtmcomm.a
CSL.DOC - document on libtmcsl.a
SSL.DOC - document on libtmssl.a
FETCH.PROTOCOL - document on partial fetch protocol