prefixes

[Brian Behlendorf <br...@hyperreal.org>]

At 05:53 PM 3/29/98 -0800, Dean Gaudet wrote:
>apapi_vformatter contains no dependencies on the core. 

Moving it to ap_vformatter was the right thing to do, then.

>I don't see the point in having 5 million different prefixes.  I don't see
>the point in having 5 different prefixes.  I would rather have one prefix
>and use it everywhere.  At the moment we've got the following:
>
>AP_	stuff that doesn't have any other prefix
>ap_	some stuff that fits your description of generic library tools
>	with no dependency on core (i.e. ap_snprintf), and some stuff
>	that does depend on core (i.e. ap_escape_quotes)

That should be cleaned up.  What other funcs besides ap_escape_quotes?
Looks like that's the only func in src/ap that takes a pool pointer as a
parameter, and could probably be modified to handle static buffers...

>apapi_  two random new core functions
>aplog_  another random core function

Looks like consensus is to use apapi_ for API functions.

>os_     some other random core functions

Wasn't this for routines that turn OS-nonspecific semantics into
OS-specific calls?  My vote would be to make this ap_.

>... and at least one more that's proposed but unused, appri_ or whatever
>you want to call it.

I think the AP_ system makes this unnecessary anymore, true?

>This is ridiculous.  Apache is 72k lines of code.  If we can't keep our
>own symbols from colliding with each other then we've got serious problems.
>We need only one prefix.

In so far as we want to have a 1) library of reusable code and 2) real API,
having distinct prefixes is helpful.

	Brian


--=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=--
"Optimism is a strategy for making                         brian@apache.org
a better future." - Noam Chomsky                        brian@hyperreal.org

Re: prefixes

[Paul Sutton <pa...@c2.net>]

On Sun, 29 Mar 1998, Brian Behlendorf wrote:
> Looks like consensus is to use apapi_ for API functions.
> 
> >os_     some other random core functions
> 
> Wasn't this for routines that turn OS-nonspecific semantics into
> OS-specific calls?  My vote would be to make this ap_.

The distinction between os_ and ap_ is that os_ does not require the
overhead of things like pools (which are going to be part of the ap_
libraries). For example, the fairly simple support programs can link
against os_ to get os-independent functionality consistent with Apache,
without needing any of the libap stuff. In general, most things in with
os_ prefixes will be short macros or inline functions, or (on many
systems) simply nops.

To my mind this is a fairly clear distinction, and having different
libraries and prefixes makes this clear to people writing Apache add ons.
But perhaps we don't need it. 

Paul

Re: prefixes

[Dean Gaudet <dg...@arctic.org>]

On Sun, 29 Mar 1998, Brian Behlendorf wrote:

> At 05:53 PM 3/29/98 -0800, Dean Gaudet wrote:
> >apapi_vformatter contains no dependencies on the core. 
> 
> Moving it to ap_vformatter was the right thing to do, then.
> 
> >I don't see the point in having 5 million different prefixes.  I don't see
> >the point in having 5 different prefixes.  I would rather have one prefix
> >and use it everywhere.  At the moment we've got the following:
> >
> >AP_	stuff that doesn't have any other prefix
> >ap_	some stuff that fits your description of generic library tools
> >	with no dependency on core (i.e. ap_snprintf), and some stuff
> >	that does depend on core (i.e. ap_escape_quotes)
> 
> That should be cleaned up.  What other funcs besides ap_escape_quotes?
> Looks like that's the only func in src/ap that takes a pool pointer as a
> parameter, and could probably be modified to handle static buffers...

But pools are a generic thing that should be part of a library.  What do
you do then when someone gets around to cleaning it up and sticking it
into libap?  Do you go around renaming apapi_escape_quotes to
ap_escape_quotes?

For example suppose palloc was rewritten like this:

    void *palloc(pool *p)
    {
	ap_block_alarms();
	ap_mutex_acquire(&alloc_mutex);
	.. do the allocation thing ..
	if (out of memory) {
	    ap_mutex_release(&alloc_mutex);
	    ap_unblock_alarms();
	    ap_fatal_exception("out of memory!");
	}
	ap_mutex_release(&alloc_mutex);
	ap_unblock_alarms();
	return result;
    }

And suppose there was a file fatal.c in libap:

    /* default fatal exception handler, just bail */
    void __attribute__((noreturn)) ap_fatal_exception(const char *msg)
    {
	fputs(msg, stderr);
	exit(1);
    }

and a file alarms.c in libap:
    
    /* default alarms handler, do nothing */
    void ap_block_alarms(void) {}
    void ap_unblock_alarms(void) {}

Then if the application has a need (i.e. httpd) it can override these
defaults and do whatever it wants to... for example the exception handler
could actually use longjmp to implement a set of nested exceptions just
like C++ provides (except we can't use for portability reasons ;).

I'd love to have pools available for use outside httpd, it would make the
library more useful for writing generic servers.  And there's not much
standing in the way of that.

Once pools are in libap you can start moving a LOT of other useful
functions into libap.  At some point you'll discover that BUFF itself
can be in libap.  It's generic too modulo the alarm handling again.

At some point you have to draw a line between what is httpd and what 
is its support library.  I'd say that line starts somewhere around the
request_rec and server_rec structures.  Stuff which manipulates those
shouldn't be in the library.  But pools, BUFFs, uri parsing, there's
lots of things that should be in the library.

> In so far as we want to have a 1) library of reusable code and 2) real API,
> having distinct prefixes is helpful.

I'm not saying we shouldn't have distinct prefixes.  I'm noting that
we need prefixes IN ADDITION to whatever prefix we choose to protect
our namespace.  I'm not against a plethora of prefixes for subsystems
within our code, but I'm against a plethora of prefixes which are there
to protect our namespace.

I see ap_, apapi_, and appri_ as prefixes which just protect the
namespace.  We need only one.

Dean