Difference between revisions of "Module inclusion"

From AOLserver Wiki
Jump to navigation Jump to search
(New page: 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 include...)
 
(First draft. Needs comment & review.)
Line 1: Line 1:
 
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.
 
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 ==
 
== Configuring a binary or combined binary & Tcl module into your server ==
As documented [[somewhere else in the wiki]], a binary module is a dynamically loadable library (.so or .dll) that will be linked into your server at startup.  To get it linked in, you:
+
As documented [[somewhere else in the wiki]], 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:
# Put the file in the right directory with an appropriate extension:
+
# 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 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.
# Tell AOLServer it's there, and that you want to use it for your virtual server.
+
#* (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).
 +
# 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/server/${servername}/modules" in nsd.tcl), add the library using the syntax:
 
#* In the modules section associated with your virtual server (e.g., "ns/server/${servername}/modules" in nsd.tcl), add the library using the syntax:
#*:<code>ns_param  ''configurationSectionName'' ''locationOfDynamicLibrary''</code>
+
#*:<code>ns_param  ''moduleName'' ''locationOfDynamicLibrary?(startupFunction)?''</code>
 
#: For example:
 
#: For example:
#:<pre><nowiki>
+
#:<pre><nowiki>ns_param  nsopenssl "${bindir}/nsopenssl.so"</nowiki></pre>
    ns_param  nsopenssl "${bindir}/nsopenssl.so"
 
</nowiki></pre>
 
 
# Restart your server. You should see a line that looks like
 
# Restart your server. You should see a line that looks like
 +
#:<pre><nowiki>[15/Apr/2008:15:39:35][31632.18446744071924766624][-main-] Notice: modload: loading '/usr/local/aolserver/bin/nsopenssl.so'</nowiki></pre>
 +
Each module included into a virtual server has its own configuration ''ns_section'' in the configuration script.  By convention, these sections are named "ns/server/{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 <code>modules/tcl/${moduleName}</code> or <code>servers/${servername}/modules/tcl/${moduleName}</code> 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 <code>int</code> variable named <code>Ns_ModuleVersion</code> 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):
 
<pre><nowiki>
 
<pre><nowiki>
[15/Apr/2008:15:39:35][31632.18446744071924766624][-main-] Notice: modload: loading '/usr/local/aolserver/bin/nsopenssl.so'
+
extern "C"
 +
{
 +
NS_EXPORT int
 +
Foo_ModInit(char* server, char* module)
 +
{
 +
...
 +
}
 
</nowiki></pre>
 
</nowiki></pre>
 +
 +
Then, in the Makefile for your module, set the MODINIT variable to the name of your function:
 +
<pre>
 +
MODINIT = Foo_ModInit
 +
</pre>
 +
== 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:
 +
# Put the library in a place AOLServer can find it.
 +
# Tell your virtual servers they should load it at startup.
 +
# 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:
 +
#*:<code>ns_param ''moduleName'' '''Tcl'''</code>
 +
#: For example:
 +
#:<pre><nowiki>ns_param nssession Tcl</nowiki></pre>
 +
[[Category:Documentation]]

Revision as of 19:10, 16 April 2008

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 somewhere else in the wiki, 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/server/${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/server/{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