diff options
author | rbb <rbb@13f79535-47bb-0310-9956-ffa450edef68> | 2000-05-19 21:44:11 +0000 |
---|---|---|
committer | rbb <rbb@13f79535-47bb-0310-9956-ffa450edef68> | 2000-05-19 21:44:11 +0000 |
commit | 3556e2757c480d41b6435b8dfa685c04fd02e225 (patch) | |
tree | ac1579a1b6a67dfc5bb33dfe6c0e58a8672e6a00 /docs | |
parent | 7ed61459129217b90b30ca3bcc81696b5314105f (diff) | |
download | libapr-3556e2757c480d41b6435b8dfa685c04fd02e225.tar.gz |
Add two APR docs. The first talks about why we are using incomplete
types. The second talks about using APR'ized programs with non-APR'ized
programs.
git-svn-id: http://svn.apache.org/repos/asf/apr/apr/trunk@60071 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs')
-rw-r--r-- | docs/incomplete_types | 84 | ||||
-rw-r--r-- | docs/non_apr_programs | 47 |
2 files changed, 131 insertions, 0 deletions
diff --git a/docs/incomplete_types b/docs/incomplete_types new file mode 100644 index 000000000..cbed77742 --- /dev/null +++ b/docs/incomplete_types @@ -0,0 +1,84 @@ +The question has been asked multiple times, "Why is APR using Incomplete +types?" This document will try to explain that. + +Incomplete types are used in APR because they can enforce portability, and +they make the APR developers job easier, as well as allowing APR to use native +types on all platforms. Imagine a scenario where APR wasn't using incomplete +types. The ap_file_t type would have to be defined as: + +typedef struct ap_file_t { + ap_pool_t *pool + char *fname; + int eof_hit; + int pipe; + ap_interval_time_t timeout; +#ifdef WIN32 + HANDLE file_handle; + DWORD dwFileAttributes; +#elif defined(OS2) + HFILE filedes; + HEV PipeSem +#else + int filedes; + int ungetchar; +#endif + +#ifndef WIN32 + int buffered; + ap_int32_flags + int isopen; + + /* Stuff for buffered mode */ + char *buffer; + int bufpos; + unsigned long dataRead; + int direction; + unsigned long filePtr; + ap_lock_t *mutex; +#endif +} ap_file_t; + +This captures the essense of what is currently being defined for ap_file_t +using incomplete types. However, using this structure leads developers to +believe that they are safe accessing any of the fields in this structure. +This is not true. On some platforms, such as Windows, about half of the +structure disappears. We could combine some of these definitions with +macros, for example: + +#ifdef WIN32 +#define filetype HANDLE +#elif OS2 +#define filetype HFILE +#else +#define filetype int +#endif + +And then in the defintion for ap_file_t, we could say: + filetype filedes; + +This gets rid of some of the complexity, by moving it off to the side, but +it is still not safe for a programmers to access the filedes field directly +outside of APR, because the programmer has no way of knowing what the actual +type is. So for example printing the filedes using printf would yield wildly +varying results on Windows and OS2 when compared to Unix. + +Another option also presents itself. Stick strictly to POSIX. This means +that all code can be shared on any POSIX compliant platform. The problem +with this is performance. One of the benefits to APR, is that it allows +developers to easily use native types on all platforms with the same code. +This has proven to provide a substantial performance boost on most non-Unix +platforms. + +Having said all of that, sometimes incomplete types just don't make sense. +For example, the first implementation of time functions used incomplete types, +which added a layer of complexity that turned out to be unnecessary. If +a platform cannot provide a simple number that represents the number of seconds +elapsed since a specifed date and time, then APR doesn't really want to +provide support for that platform. + +APR is trying hard to provide a balance of incomplete and complete types, +but like all things, sometimes the developers make mistakes. If you are +using APR and find that there is an incomplete type that doesn't need to be +an incomplete type, please let us know, we are more than willing to listen +and design parts of APR that do not use incomplete types. + diff --git a/docs/non_apr_programs b/docs/non_apr_programs new file mode 100644 index 000000000..47b7d8ec6 --- /dev/null +++ b/docs/non_apr_programs @@ -0,0 +1,47 @@ +How do I use APR'ized programs in connection with programs that don't +use APR? These darn incomplete types don't let me fill out the APR types. + +The APR developers acknowledge that most programs are not using APR, and +we don't expect them to migrate to using APR just because APR has been +released. So, we have provided a way for non-APR'ized programs to interact +very cleanly with APR. + +There are a set of programs, all documented in apr_portable.h, which allow +a programmer to either get a native type from an APR type, or to setup an +APR type from a native type. + +For example, if you are writing an add-on to another program that does not use +APR for file I/O, but you (in your infinite wisdom) want to use APR to make +sure your section is portable. Assume the program provides a type foo_t with +a file descriptor in it (fd). + +void function_using_apr(foo_t non_apr_struct, ap_pool_t *p) +{ + ap_file_t *apr_file = NULL; + + ap_put_os_file(&apr_file, &non_apr_struct->fd, p); + + ... +} + +There are portable functions for each APR incomplete type. They are all +called ap_put_os_foobar(), and they each take the same basic arguments, a +pointer to a pointer to the incomplete type (the last pointer in that list +should be NULL), a pointer to the native type, and a pool. Each of these can +be found in apr_portable.h. + +If you have to do the exact opposite (take an APR type and convert it to a +native type, there are functions for that too. For example: + +void function_not_using_apr(apr_file_t *apr_file) +{ + int unix_file_desc; + + ap_get_os_file(&unix_file_desc, apr_file); + + ... +} + +For each ap_put_os_foobar, there is a corresponding ap_get_os_file. These are +also documented in apr_portable.h. + |