httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Tony Finch <>
Subject Re: A couple of important features for 2.0
Date Tue, 21 Mar 2000 00:29:21 GMT
"Bill Stoddard" <> wrote:
>> 2)  Freeze the current API.  When a new feature is required, add a new
>> function instead of modifying the old one.
>This with 1) helps even more. Bloats the code, stifles creativity and just
>doesn't fit in with open source development philosophy. If an API is just
>not right, it should be changed.  Maintaining deprecated APIs is common
>practice in commercial software development but there is a price to pay in
>complexity. And complexity is an open source project killer, IMHO; it raises
>the project entry barrier and bugs increase non-linearly with complexity.

These are the issues I was trying to address with the API jump table
but I really don't like that idea for a number of reasons (mostly
variations on the theme of run-time complexity).

I came up with an alternative this evening which avoids the
performance problems of using a jump table by using pre-processor
magic instead. To #include the Apache API a module says something like
	#define AP_API_VERSION 20000320
	#include "ap_api.h"
and then proceeds to program to the API without worrying about
changing versions -- source compatibility and binary compatibility.

The core is programmed in a similar way, except it always uses the
most recent API version, e.g. all core code says
	#include "ap_api_latest.h"
	#include "ap_api.h"
before doing anything else. However, when an API change is made, the
old version of the function that has been changed is retained
(probably as a wrapper calling the new version). Any old versions are
distinguished from the new one by mangling their names with different
date strings, e.g.
and the latest version of the function has an unmangled name.

All unmangled names are really mangled names in disguise: the
"ap_api.h" header expands them to whatever is appropriate, according
to the value of AP_API_VERSION. "ap_api.h" knows when each API
function was changed, and when #included does
	#define ap_foo ap_foo_XXXXXXXX
for the largest XXXXXX not greater than AP_API_VERSION (so if I say
	#define AP_API_VERSION 20000202
	#include "ap_api.h"
then when I use ap_foo I'll actually be using ap_foo_19991207). A
little tool will be required to maintain "ap_api_latest.h" and
"ap_api.h", using a source file with content similar to what is in
"ap_mmn.h" right now (i.e. I don't expect the maintenance burden to be
a great deal worse).

This doesn't solve the problem of changing data structures; I think
that will have to be dealt with by adding accessor functions to the
API and making third party modules use them.

369 the barnacle-encrusted bilge pump on your sunken dreams

View raw message