← Back to branch summary

~ubuntu-branches/ubuntu/feisty/apache2/feisty

« back to all changes in this revision

Viewing changes to srclib/apr/docs/incomplete_types

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Barth
  • Date: 2006-12-09 21:05:45 UTC
  • mfrom: (0.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20061209210545-h70s0xaqc2v8vqr2
Tags: 2.2.3-3.2
http://bugs.debian.org/396265
* Non-maintainer upload.
* 043_ajp_connection_reuse: Patch from upstream Bugzilla, fixing a critical
  issue with regard to connection reuse in mod_proxy_ajp.
  Closes: #396265

Show diffs side-by-side

added added

removed removed

Lines of Context:
srclib/apr/docs/incomplete_types
 
1
The question has been asked multiple times, "Why is APR using Incomplete
 
2
types?"  This document will try to explain that.
 
3
 
 
4
Incomplete types are used in APR because they can enforce portability, and
 
5
they make the APR developers job easier, as well as allowing APR to use native
 
6
types on all platforms.  Imagine a scenario where APR wasn't using incomplete
 
7
types.  The ap_file_t type would have to be defined as:
 
8
 
 
9
typedef struct ap_file_t {
 
10
    ap_pool_t *pool
 
11
    char *fname;
 
12
    int eof_hit;
 
13
    int pipe;
 
14
    ap_interval_time_t timeout;
 
15
#ifdef WIN32
 
16
    HANDLE file_handle;
 
17
    DWORD dwFileAttributes;
 
18
#elif defined(OS2)
 
19
    HFILE filedes;
 
20
    HEV PipeSem
 
21
#else
 
22
    int filedes;
 
23
    int ungetchar;
 
24
#endif
 
25
 
 
26
#ifndef WIN32
 
27
    int buffered;
 
28
    ap_int32_flags
 
29
    int isopen;
 
30
   
 
31
    /* Stuff for buffered mode */
 
32
    char *buffer;
 
33
    int bufpos;
 
34
    unsigned long dataRead;
 
35
    int direction;
 
36
    unsigned long filePtr;
 
37
    ap_lock_t *mutex; 
 
38
#endif
 
39
} ap_file_t;
 
40
 
 
41
This captures the essense of what is currently being defined for ap_file_t
 
42
using incomplete types.  However, using this structure leads developers to
 
43
believe that they are safe accessing any of the fields in this structure.
 
44
This is not true.  On some platforms, such as Windows, about half of the
 
45
structure disappears.  We could combine some of these definitions with
 
46
macros, for example:
 
47
 
 
48
#ifdef WIN32
 
49
#define filetype HANDLE
 
50
#elif OS2
 
51
#define filetype HFILE
 
52
#else
 
53
#define filetype int
 
54
#endif
 
55
 
 
56
And then in the defintion for ap_file_t, we could say:
 
57
    filetype filedes;
 
58
 
 
59
This gets rid of some of the complexity, by moving it off to the side, but
 
60
it is still not safe for a programmers to access the filedes field directly 
 
61
outside of APR, because the programmer has no way of knowing what the actual 
 
62
type is.  So for example printing the filedes using printf would yield wildly 
 
63
varying results on Windows and OS2 when compared to Unix.
 
64
 
 
65
Another option also presents itself.  Stick strictly to POSIX.  This means
 
66
that all code can be shared on any POSIX compliant platform.  The problem
 
67
with this is performance.  One of the benefits to APR, is that it allows
 
68
developers to easily use native types on all platforms with the same code.
 
69
This has proven to provide a substantial performance boost on most non-Unix
 
70
platforms.
 
71
 
 
72
Having said all of that, sometimes incomplete types just don't make sense.
 
73
For example, the first implementation of time functions used incomplete types,
 
74
which added a layer of complexity that turned out to be unnecessary.  If
 
75
a platform cannot provide a simple number that represents the number of seconds
 
76
elapsed since a specifed date and time, then APR doesn't really want to 
 
77
provide support for that platform.
 
78
 
 
79
APR is trying hard to provide a balance of incomplete and complete types, 
 
80
but like all things, sometimes the developers make mistakes.  If you are
 
81
using APR and find that there is an incomplete type that doesn't need to be
 
82
an incomplete type, please let us know, we are more than willing to listen
 
83
and design parts of APR that do not use incomplete types.
 
84