This directory contains support files to enable AOLServer 3.4 to load and use the XOTcl 1.0 extension. Following files are distributed by this patch: o. this file o. the "modules" directory; contains files and directories to be put in the same place in AOLserver runtime directory. o. the "patchfile-3.4 file; contains commands for the patch utility. It should be copied to the root of AOLserver source directory. Regular usage for XOTcl under AOLserver is to declare all your needed classes, objects, etc at the startup time. The AOLserver will then take care to replicate all of them in connection threads (or any other thread). It will also take care to automatically destroy them at thread-exit time. You have to dig thru the AOLserver docs in order to find information on how to make AOLserver-savvy Tcl and/or XOtcl library files, where to put them, so they get recognized and loaded by the server, etc, etc. I'm not going to write about this here - I assume you know it already. Why need to patch AOLserver 3.4? -------------------------------- The AOLserver is a multithreaded application and web server using Tcl as it's primary extension language. Each server thread gets its own Tcl interpreter where most of the processing takes place. In order to simplify task of creating and properly initializing Tcl interpreters for each new thread, AOLserver does some additional processing at the server-start time. During startup, the startup-thread performs many tasks, one of which is to load declared shared-libraries and source declared Tcl files. What to load/source is declared in the server configuration file. After that, server runs an introspective script which collects names of all commands, namespaces, variables, etc, found in the interpreter at that moment. The list of commands is represented internally as linked-list of Tcl command structures. All other Tcl data (procedures, namespaces, variables) are collected in a big synthetized Tcl script - the init script. When creating the new Tcl interp, AOLserver walks the command linked-list and creates all commands found there. Afterwards, the init script is sourced and this re-creates all namespaces, procedures and variables. So the new Tcl interpreter for new thread is (ahem, should be...) more or less the same as in the initial startup thread. All of this can be learned from nsd/tclinit.c file... This process works mostly fine. There are however couple of culprits there. One of the most vulnerable points is the linked list of Tcl command structs. A Tcl command structure stores, among others, the command-deletion callback. This callback is activated each time a command is deleted from the interpreter. Now, this delete-callback accepts a (ClientData) pointer which gets passed to the callback. This pointer is also stored in the Tcl command structure. Now, what happens if we share the Tcl command structure among threads, more precisely, use the same command structure to create command in one or many different threads ? You're right. Shit happens ! Again, more precisely, many command deletion callbacks get *same* client data pointer which may (and mostly does) result in memory trashing. What we do to avoid it? We simply avoid copying commands with declared deletion callbacks in the first place (patch the nsd/tclstubs.cpp, the NsTclCreateCommand() function) Then, we make sure that our extension registers the AOLserver AtCreate callback which gets activated each time a new Tcl interp is being created. The extension takes care to stuff all what's needed in the callback so the interpreter gets properly configured. A minor inconvenience is that AOLserver calls these (AtCreate) callbacks *after* running the init script, which is bad. We therefore changed this behaviour, so handlers are invoked *before* the script gets evaluated. This way, the commands collected in the script, which may (and usually do) reference extension commands, will run properly (patch the nsd/tclinit.c, the CreateInterp() function). How to make AOLserver 3.4 to load and use XOTcl 1.0 ? ------------------------------------------------------- 1. Unpack the xotcl-aolserver patch somewhere on your filesystem: % cd % tar xvzf ~/xotcl-aolpatch.tar.gz % P=~/xotcl-aolpatch 2. Get a new AOLserver 3.4 distribution from http://www.aolserver.com/archive/server/aolserver-3.4.tar.gz Unpack the original distribution. Copy the patch file from the patch directory above to the server source distribution directory. NOTE: In following example, I assume you will use the default directory /usr/local/aolserver for AOLserver runtime. % AOLDIST=~/aolserver-3.4 % AOLRUNT=/usr/local/aolserver % tar xvzf aolserver-3.4.tar.gz % cp $P/patchfile-3.4 $AOL/ % cd $AOLDIST/ % patch -p0 < patchfile-3.4 NOTE: Patch should modify following files only: nsd/tclinit.c nsd/tclstubs.cpp 3. Replace one original file: % mv $AOLDIST/tcl/namespace.tcl $AOLDIST/tcl/namespace.tcl-orig % cp $P/modules/tcl/namespace.tcl $AOLDIST/tcl/ 4. Compile and install the AOLserver. % make % make install This should run cleanly on most systems. Now, add one additional file/directory to AOLserver home directory: % mkdir $AOLRUNT/modules/tcl/xotcl % cp $P/modules/tcl/xotcl/classcopy.xotcl $AOLRUNT/modules/tcl/xotcl This is all you have to do for the AOLserver. You should be able to start your server now. But, don't do this until you have prepared the XOTcl shared library. This is explained below. How to make XOTcl 1.0 to load into the AOLserver 3.4? ------------------------------------------------------ 1. Fetch XOTcl 1.0 version from http://www.xotcl.org/download/xotcl-full-1.0.tar.gz NOTE: In following example, I assume you will use the default directory /usr/local/aolserver for AOLserver runtime. % AOLRUNT=/usr/local/aolserver % tar zxvf xotcl-1.0.tar.gz % cd xotcl-1.0/unix 3. Run configure. % ./configure 4. Edit Makefile.in and uncomment the line wih AOL_DEFINES if necessary (if you expand the tar file withing the aolserver source tree, the settings are adjusted automatically) 5. Build the XOTcl shared library (the .so file). Note that you have to build only the shared library, no executables. % make libs 6. Now, you should copy the library to the server binary directory. % cp libxotcl1.0.so $AOLRUNT/bin You also have to tweak the server startup file to load the library. Typically you have to add a line to the modules-section ns_section "ns/server/${servername}/modules" ... ns_param xotcl ${bindir}/libxotcl1.0.so Consult the AOLserver documentation on how to do this. You can start the AOLserver now. If all's well, you should be able to see following line in your server log: [12/Oct/2001:11:55:08][13467.1][-main-] Notice: xotcl module version 1.0 If you have any problems, contact me at mailto:zoran@archiware.com Have fun! Zoran Vasiljevic Archiware Inc.