1 The question has been asked multiple times, "Why is APR using Incomplete
2 types?" This document will try to explain that.
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:
9 typedef struct ap_file_t {
14 ap_interval_time_t timeout;
17 DWORD dwFileAttributes;
31 /* Stuff for buffered mode */
34 unsigned long dataRead;
36 unsigned long filePtr;
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
49 #define filetype HANDLE
51 #define filetype HFILE
56 And then in the defintion for ap_file_t, we could say:
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.
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
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.
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.