Mailing-List: contact dev-help@httpd.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@httpd.apache.org
Date: Thu, 12 Aug 2004 02:51:13 -0400
From: Glenn Strauss <gs-apache-dev@gluelogic.com>
To: dev@httpd.apache.org
Subject: Re: RFE: ap_input_mode_t as bitflags
Message-ID: <20040812065113.GA7112@netspace.org>
References: <20040811211646.GA12727@netspace.org>
 <2279233FA75D61F5583C9654@2B9FC815C12CF19931FDCE0B>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <2279233FA75D61F5583C9654@2B9FC815C12CF19931FDCE0B>
User-Agent: Mutt/1.4.1i

On Wed, Aug 11, 2004 at 03:51:13PM -0700, Justin Erenkrantz wrote:
> --On Wednesday, August 11, 2004 5:16 PM -0400 Glenn Strauss 
> <gs-apache-dev@gluelogic.com> wrote:
> 
> >I'm finding ap_input_mode_t very restrictive as a linear enum
> >and would like to make it an enum of bitflags.
> 
> Please back up a bit.
> 
> Why do you think the modes should be combined?  -- justin

Short answer:
-------------
I am refactoring most of the input filtering for more consistent
behavior and much greater code reuse.  However, two incompatible
changes are needed, and with Apache 2.2 in sight, I wanted to
introduce those changes now.

Those changes are: ap_input_mode_t becomes bitflags, and input
filters must check for bitflags instead of exact values
(mode & AP_MODE_GETLINE) instead of (mode == AP_MODE_GETLINE)
Also, AP_MODE_GETLINE should not return partial lines.


More details:
-------------
Why bitflags, you ask?

I had hoped to introduce this a bit more slowly,
but here is a brief peek without too much explanation:

I'd like any of the following to be legal values:

AP_MODE_BYTES
AP_MODE_BYTES | AP_MODE_PASS_SPECIALS
AP_MODE_BYTES | AP_MODE_PEEK
AP_MODE_LINE
AP_MODE_LINE | AP_MODE_PEEK
AP_MODE_LINE | AP_MODE_MIME_FOLDING
AP_MODE_LINE | AP_MODE_MIME_FOLDING | AP_MODE_PEEK

typedef enum {

    /** The filter should return at most one line of CRLF data.
     *  (If a potential line is too long or no CRLF is found,
     *   the line is not returned, an error is.)
     */
    AP_MODE_LINE = 1,

    /** The filter should return at most readbytes data. */
    AP_MODE_BYTES = 2,

    /** The filter should pass any special buckets (not in-memory) as long as it
     *  does not need to perform any processing on them (translation or protocol
     *  delimiting) (augments AP_MODE_BYTES; mutually exclusive w/ AP_MODE_PEEK)
     */
    AP_MODE_PASS_SPECIALS = 4,

    /** The filter read should be treated as speculative and any returned
     *  data should be stored for later retrieval in another mode.
     *  (augments AP_MODE_BYTES or AP_MODE_LINE)
     */
    AP_MODE_PEEK = 8,

    /** When reading lines, look for MIME-folded continuations as well
     *  (augments AP_MODE_LINE)
     */
    AP_MODE_MIME_FOLDING = 16
                                                                                
} ap_input_mode_t;


I think that input filtering is difficult to use and leads to a lot
of code duplication between modules.  For example, the behavior of
line-mode is vauge and requires that callers re-parse the brigade
to check for complete lines.  I've got a whole litany of things,
including bad code examples of brigade parsing in the Apache core,
but that's another post.

One advantage of the new API:
MIME continuation lines are used so often (HTTP headers/trailers,
email message headers, MIME encapsulation, ...) that they should be
part of the core API.  Instead of code duplication (witness
ap_rgetline_core() and ap_get_mime_headers_core() both implementing
continuation line unfolding), AP_MODE_LINE | AP_MODE_MIME_FOLDING
does not return a partial line.  It only returns a complete line
including continuations.  Simplifying things a bit for now, this
allows caller to know that if its brigade is returned non-empty,
that the line is complete, including continuations, without caller
having to re-parse the line to double-check.

(More posts to follow, but I do not wish to flood the list if no
 one wants to engage the conversation.)

Cheers,
Glenn