1251875SpeterThe question has been asked multiple times, "Why is APR using Incomplete 2251875Spetertypes?" This document will try to explain that. 3251875Speter 4251875SpeterIncomplete types are used in APR because they can enforce portability, and 5251875Speterthey make the APR developers job easier, as well as allowing APR to use native 6251875Spetertypes on all platforms. Imagine a scenario where APR wasn't using incomplete 7251875Spetertypes. The ap_file_t type would have to be defined as: 8251875Speter 9251875Spetertypedef struct ap_file_t { 10251875Speter ap_pool_t *pool 11251875Speter char *fname; 12251875Speter int eof_hit; 13251875Speter int pipe; 14251875Speter ap_interval_time_t timeout; 15251875Speter#ifdef WIN32 16251875Speter HANDLE file_handle; 17251875Speter DWORD dwFileAttributes; 18251875Speter#elif defined(OS2) 19251875Speter HFILE filedes; 20251875Speter HEV PipeSem 21251875Speter#else 22251875Speter int filedes; 23251875Speter int ungetchar; 24251875Speter#endif 25251875Speter 26251875Speter#ifndef WIN32 27251875Speter int buffered; 28251875Speter ap_int32_flags 29251875Speter int isopen; 30251875Speter 31251875Speter /* Stuff for buffered mode */ 32251875Speter char *buffer; 33251875Speter int bufpos; 34251875Speter unsigned long dataRead; 35251875Speter int direction; 36251875Speter unsigned long filePtr; 37251875Speter ap_lock_t *mutex; 38251875Speter#endif 39251875Speter} ap_file_t; 40251875Speter 41251875SpeterThis captures the essense of what is currently being defined for ap_file_t 42251875Speterusing incomplete types. However, using this structure leads developers to 43251875Speterbelieve that they are safe accessing any of the fields in this structure. 44251875SpeterThis is not true. On some platforms, such as Windows, about half of the 45251875Speterstructure disappears. We could combine some of these definitions with 46251875Spetermacros, for example: 47251875Speter 48251875Speter#ifdef WIN32 49251875Speter#define filetype HANDLE 50251875Speter#elif OS2 51251875Speter#define filetype HFILE 52251875Speter#else 53251875Speter#define filetype int 54251875Speter#endif 55251875Speter 56251875SpeterAnd then in the defintion for ap_file_t, we could say: 57251875Speter filetype filedes; 58251875Speter 59251875SpeterThis gets rid of some of the complexity, by moving it off to the side, but 60251875Speterit is still not safe for a programmers to access the filedes field directly 61251875Speteroutside of APR, because the programmer has no way of knowing what the actual 62251875Spetertype is. So for example printing the filedes using printf would yield wildly 63251875Spetervarying results on Windows and OS2 when compared to Unix. 64251875Speter 65251875SpeterAnother option also presents itself. Stick strictly to POSIX. This means 66251875Speterthat all code can be shared on any POSIX compliant platform. The problem 67251875Speterwith this is performance. One of the benefits to APR, is that it allows 68251875Speterdevelopers to easily use native types on all platforms with the same code. 69251875SpeterThis has proven to provide a substantial performance boost on most non-Unix 70251875Speterplatforms. 71251875Speter 72251875SpeterHaving said all of that, sometimes incomplete types just don't make sense. 73251875SpeterFor example, the first implementation of time functions used incomplete types, 74251875Speterwhich added a layer of complexity that turned out to be unnecessary. If 75251875Spetera platform cannot provide a simple number that represents the number of seconds 76251875Speterelapsed since a specifed date and time, then APR doesn't really want to 77251875Speterprovide support for that platform. 78251875Speter 79251875SpeterAPR is trying hard to provide a balance of incomplete and complete types, 80251875Speterbut like all things, sometimes the developers make mistakes. If you are 81251875Speterusing APR and find that there is an incomplete type that doesn't need to be 82251875Speteran incomplete type, please let us know, we are more than willing to listen 83251875Speterand design parts of APR that do not use incomplete types. 84251875Speter 85