This is a prototype for writing Apache modules using Objective-C bundles. Only people who know about the Apache module API should try this stuff ...
ApacheAPI is a toolkit to write dynamically loadable Apache modules in Objective-C with a Foundation library like libFoundation or gstep-base.
The intention is not to add another abstraction layer on top of Apache but only to provide a convenient interface for Objective-C programmers. The kit provides almost the complete Apache API in the form of Objective-C classes.
So you can:
More abstractions and richer page generation API is left to other frameworks which might be build around this kit.
ApacheAPI adds another plain-C module called mod_gsbundle. This module
provides a single configuration function called "LoadApacheBundle" which is
used to load Foundation library NSBundle objects.
Each ApacheAPI modules is implemented as a
NSBundle.
After mod_gsbundle loaded the bundle, it instantiates a singleton object
of the principal class of the bundle (set using the Bundle_PRINCIPAL_CLASS
gstep-make macro).
An object is used instead of the class object itself so that one can easily
use instance variables and because it better supports the reload-semantics
of the Apache config process (this object is recreated for each configure
run !)
Using config files stored inside of the bundle gsbundle now automagically creates the Apache module, handler and command structures for the bundle principal object. As soon this auto-generated module is registered with Apache this object will receive Objective-C messages from Apache.
The implementation of an Objective-C module is mostly tricky because
Apache makes use of module *unloading* during it's configuration process.
This easily confuses the Objective-C runtime which currently isn't
prepared to unload objects (neither the NeXT/Apple runtime nor the GNU
runtime).
ApacheAPI solves this problem by the help of another small stub library
which implements the module itself.
Another problem is that the Apache API callbacks mostly lose their "identity" after module setup (the callback functions do not receive a "backpointer" to their module structure). This is worked around by the kit by providing a stub-generation shell script. The generated code contains Apache module stubs and a module Objective-C class which is used to dispatch the callbacks to Objective-C.
Last but not least, Apache configuration. As mentioned above Apache unloads all modules at least once while starting up (and again if a HUP signal is send). This is because Apache executes the configuration process *twice*, as Scott Hess says:
The standard sequence is: parent runs through the entire config process. parent unwinds the entire config process. parent runs through the entire config process. parent creates the listen socket(s). parent forks. children accept connections. -X only changes the last two items. The parent no longer forks, and it goes into the accept loop itself. But the config passes are all the same. The config passes are the way they are so that when you send a reconfig type signal, you already know that the parent can unwind the current config correctly. Think of it as building up a good config, and then _immediately_ doing a reconfig.So, don't be confused if your configuration callbacks are called multiple times :-)
Coredumps of Apache when restarting: This is usually if you installed a freshly compiled bundle without stopping Apache (I guess because the bundle is memory-mapped into Apache).