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