xref: /external/clearsilver/mod_ecs

mod_ecs - Apache Embedded ClearSilver CGI Module
-------------------------------------------------------
mod_ecs is based on a heavily modified version of mod_ecgi from:
http://www.webthing.com/software/mod_ecgi.html

This directory contains an Apache module which is designed to work with
the ClearSilver CGI Kit.  The point of this Apache module is
performance, if your server is under sufficient load that the overhead
of forking and execing the CGI for every request is too much, this
module is for you.  This module is also useful if you want some of the
benefits of having a long-lived program: ie, the CGI can maintain
connections to data sources such as databases or cache data in memory.
The chief disadvantage is the same thing: your CGI becomes a long lived
process, and you have to watch that you don't hold connections or memory
that you don't want to.  You might want to look into the Apache
configuration directives for limiting the number of connections that
each child process handles: MaxRequestsPerChild.

If you are already using the full ClearSilver CGI Kit, all you need to
do to compile for the embedded ClearSilver is compile to a shared
library instead of to an executable.  For instance, under Linux:

 Executable: ld -o static.cgi -lneo_cgi -lneo_cs -lneo_util
 Shared Library: ld -shared -fPic -o static.cso -lneo_cgi -lneo_cs -lneo_util

Also, remember not to call exit(), as this will cause the entire Apache
child to exit.

There are two extra functions you can have in your CGI that the embedded
ClearSilver module will try to find and call if they exist.  They are:
void ECSInit(void);
and
void ECSCleanup(void);

The first is called when the embedded CGI is loaded, the second before
the embedded CGI is unloaded.

This module supports the following three Apache configuration
directives:
ECSReload <yes/no>
  When yes, mod_ecs will stat the .cso every time its run, to see if the 
  file on disk has been updated.  If it has been updated, it will reload
  the shared file from disk.  This incurs some performance overhead, and
  when a change does occur, it removes most of the gains of ECSPreload.
  Notice also that on many operating systems, changing a shared library
  on disk that has been demand loaded can cause problems such as unexpected
  core dumps.  This setting is most useful for development environments where
  speed/throughput requirements aren't as high, but constant change is a 
  factor.
ECSDepLib <path>
  Brings the benefits of ECSPreload to dependent shared libraries.  Will
  cause mod_ecs to dlopen() the library at apache initialization time.
  This can be avoided by using ECSPreload and having an ECSInit()
  function in your library which does the shared library initialization.
ECSPreload <path>
  This function can be used to preload any shared libraries that you might
  be calling later.  This allows you to hide the latency of load/init time
  from your users by doing it once at apache initialization.

Requirements:
  A later version of Apache 1.3.x, probably 1.3.12+.

To Compile:
To dynamically load this module (assuming your copy of Apache is
compiled to use mod_so), do:

  /path/to/apxs -c mod_ecs.c

Optionally, to (semi-)automatically install the module, do:
  /path/to/apxs -i -a -n ecs mod_ecs.so

Or, you can just edit your httpd.conf file yourself, adding the
following lines:
  LoadModule ecs_module /path/to/installed/mod_ecs.so
  # This line needs to be after and ClearModuleList command
  AddModule mod_ecs.c

There are two ways to tell Apache that a file is an embedded ClearSilver
CGI shared library, both are by extension.  Typically, we use the .cso
extension.  You can either use AddHandler or AddType:
  AddHandler ecs-cgi .cso
  AddType application/x-ecs-cgi