Module inclusion

Typical AOLServer modules are written in either Tcl, C, or some combination of those languages (though, of course, new languages can be added via the C module interface). They are included into your runtime using a section of the AOLServer Configuration file.

Configuring a binary or combined binary & Tcl module into your server

As documented in the AOLServer C Developer's Guide, a binary module is a dynamically loadable library (.so or .dll) that will be linked into the server at startup (by the fact that it provides an external function called "Ns_ModuleInit" and an external integer called "Ns_Version"). To get AOLServer to try to link it in:

1. Put the file in the right directory:
   • In the default configuration of AOLServer, the right place is usually {your installation directory}/bin (e.g., /usr/local/aolserver/lib). In the AOLServer configuration file, by convention, this directory name is written as "${bindir}". Some installations use a separate "${homedir}/lib" (thus ${libdir}) directory.
   • (In AOLServer 3.x and below, the convention for the extension for dynamic libraries was to follow the convention of the host operating system; e.g., for Linux/Unix to use ".so" and for Windows to use ".dll". In AOLServer 4.0 and above, we just use ".so" for all dynamic libraries to simplify the configuration and packaging).
2. Tell AOLServer that it should provide that module to the virtual servers you're configuring.
   • In the modules section associated with your virtual server (e.g., "ns/servers/${servername}/modules" in nsd.tcl), add the library using the syntax:

     ns_param moduleName locationOfDynamicLibrary?(startupFunction)?

   For example:

   ns_param   nsopenssl "${bindir}/nsopenssl.so"

3. Restart your server. You should see a line that looks like

   [15/Apr/2008:15:39:35][31632.18446744071924766624][-main-] Notice: modload: loading '/usr/local/aolserver/bin/nsopenssl.so'

Each module included into a virtual server has its own configuration ns_section in the configuration script. By convention, these sections are named "ns/servers/{servername}/module/{moduleName}", where the moduleName is taken from the ns_param used to include the library in the "modules" section. Modules usually provide some guidance about how to write this section, perhaps by providing their own "nsd.tcl" files in the module directory.

The library, of course, is only dynamically linked into the AOLServer executable once (that is the nature of dynamic linking in most operating systems). It is initialized (that is, its initialization function is called) once per virtual server it is configured into. There is no mechanism for removing a dynamically loaded module once loaded; the server must be restarted to remove that context.

If a module also contains Tcl components, those should be installed into the appropriate modules/tcl/${moduleName} or servers/${servername}/modules/tcl/${moduleName} directory (as described below). Configuring AOLServer to use the dynamic library component automatically ensures that the Tcl components will be used as well.

At initialization, all dynamic loading is done before all Tcl module initialization. Modules are loaded in the order they are listed in the modules section of the configuration file.

Since the dynamic loading is done before Tcl module initialization, a convenient development pattern has emerged in the AOLServer community. A dynamically loaded module often provides some very general purpose Tcl commands; then its accompanying Tcl files are used to specialize those commands for a particular purpose. For example, an "nsldap" module may provide general LDAP interface commands, and then also provide examples, in Tcl, for using those commands to authenticate users, find their groups, etc.

Startup Functions & Version Constraints (Ns_ModuleInit and Ns_ModuleVersion)

Each dynamically loaded module must export (in "C" convention) an initialization function that conforms to the typedef Ns_ModuleInitProc. By convention, this startup function is named "Ns_InitProc", but if a module exports a different name, that can be accomodated in the configuration file (as shown above). Dynamically loaded modules should export an int variable named Ns_ModuleVersion that describes the version of the module.

The build system for AOLServer 4.x makes this straightforward. Define your module initialization function using any name you'd like (the following is taken from a C++ file):

extern "C"
{
    NS_EXPORT int
    Foo_ModInit(char* server, char* module)
    {
        ...
    }
}

Then, in the Makefile for your module, set the MODINIT variable to the name of your function:

MODINIT = Foo_ModInit

Tcl Modules

Developing Tcl modules for use with AOLServer is just as straightforward, but have some interesting additional features: a Tcl library really can be installed only into the Tcl interpreters for a specific virtual server, and they can usually be reloaded dynamically.

The steps are the same:

1. Put the library in a place AOLServer can find it.
2. Tell your virtual servers they should load it at startup.
3. Restart your server so they do that.

Tcl libraries are usually a set of tcl files, and so are installed into directories named after the library. The directories to use are "${homedir}/modules/tcl/${moduleName}" for libraries that any virtual server may load, or ${homedir}/servers/${servername}/modules/tcl/${moduleName}" for libraries that will only be loaded into specific virtual servers.

If the directory contains a file named "init.tcl", it will be "sourced" into Tcl interpreters before any other files in that directory.

The syntax for loading pure-Tcl library modules is:

ns_param moduleName Tcl

For example:

ns_param nssession Tcl