1mod_ecs - Apache Embedded ClearSilver CGI Module
2-------------------------------------------------------
3mod_ecs is based on a heavily modified version of mod_ecgi from:
4http://www.webthing.com/software/mod_ecgi.html
5
6This directory contains an Apache module which is designed to work with
7the ClearSilver CGI Kit.  The point of this Apache module is
8performance, if your server is under sufficient load that the overhead
9of forking and execing the CGI for every request is too much, this
10module is for you.  This module is also useful if you want some of the
11benefits of having a long-lived program: ie, the CGI can maintain
12connections to data sources such as databases or cache data in memory.
13The chief disadvantage is the same thing: your CGI becomes a long lived
14process, and you have to watch that you don't hold connections or memory
15that you don't want to.  You might want to look into the Apache
16configuration directives for limiting the number of connections that
17each child process handles: MaxRequestsPerChild.
18
19If you are already using the full ClearSilver CGI Kit, all you need to
20do to compile for the embedded ClearSilver is compile to a shared
21library instead of to an executable.  For instance, under Linux:
22
23 Executable: ld -o static.cgi -lneo_cgi -lneo_cs -lneo_util
24 Shared Library: ld -shared -fPic -o static.cso -lneo_cgi -lneo_cs -lneo_util
25
26Also, remember not to call exit(), as this will cause the entire Apache
27child to exit.
28
29There are two extra functions you can have in your CGI that the embedded
30ClearSilver module will try to find and call if they exist.  They are:
31void ECSInit(void);
32and
33void ECSCleanup(void);
34
35The first is called when the embedded CGI is loaded, the second before
36the embedded CGI is unloaded.
37
38This module supports the following three Apache configuration
39directives:
40ECSReload <yes/no>
41  When yes, mod_ecs will stat the .cso every time its run, to see if the
42  file on disk has been updated.  If it has been updated, it will reload
43  the shared file from disk.  This incurs some performance overhead, and
44  when a change does occur, it removes most of the gains of ECSPreload.
45  Notice also that on many operating systems, changing a shared library
46  on disk that has been demand loaded can cause problems such as unexpected
47  core dumps.  This setting is most useful for development environments where
48  speed/throughput requirements aren't as high, but constant change is a
49  factor.
50ECSDepLib <path>
51  Brings the benefits of ECSPreload to dependent shared libraries.  Will
52  cause mod_ecs to dlopen() the library at apache initialization time.
53  This can be avoided by using ECSPreload and having an ECSInit()
54  function in your library which does the shared library initialization.
55ECSPreload <path>
56  This function can be used to preload any shared libraries that you might
57  be calling later.  This allows you to hide the latency of load/init time
58  from your users by doing it once at apache initialization.
59
60Requirements:
61  A later version of Apache 1.3.x, probably 1.3.12+.
62
63To Compile:
64To dynamically load this module (assuming your copy of Apache is
65compiled to use mod_so), do:
66
67  /path/to/apxs -c mod_ecs.c
68
69Optionally, to (semi-)automatically install the module, do:
70  /path/to/apxs -i -a -n ecs mod_ecs.so
71
72Or, you can just edit your httpd.conf file yourself, adding the
73following lines:
74  LoadModule ecs_module /path/to/installed/mod_ecs.so
75  # This line needs to be after and ClearModuleList command
76  AddModule mod_ecs.c
77
78There are two ways to tell Apache that a file is an embedded ClearSilver
79CGI shared library, both are by extension.  Typically, we use the .cso
80extension.  You can either use AddHandler or AddType:
81  AddHandler ecs-cgi .cso
82  AddType application/x-ecs-cgi
83
84