| APRDesign.html (302408) | APRDesign.html (362181) |
|---|---|
| 1<HTML> 2<HEAD><TITLE>APR Design Document</TITLE></HEAD> 3<BODY> 4<h1>Design of APR</h1> 5 6<p>The Apache Portable Run-time libraries have been designed to provide a common 7interface to low level routines across any platform. The original goal of APR 8was to combine all code in Apache to one common code base. This is not the --- 138 unchanged lines hidden (view full) --- 147found in the test/ directory. Include is a directory which stores all 148required APR header files for external use.</p> 149 150<h2>Creating an APR Type</h2> 151 152<p>The current design of APR requires that most APR types be incomplete. 153It is not possible to write flexible portable code if programs can access 154the internals of APR types. This is because different platforms are | 1<HTML> 2<HEAD><TITLE>APR Design Document</TITLE></HEAD> 3<BODY> 4<h1>Design of APR</h1> 5 6<p>The Apache Portable Run-time libraries have been designed to provide a common 7interface to low level routines across any platform. The original goal of APR 8was to combine all code in Apache to one common code base. This is not the --- 138 unchanged lines hidden (view full) --- 147found in the test/ directory. Include is a directory which stores all 148required APR header files for external use.</p> 149 150<h2>Creating an APR Type</h2> 151 152<p>The current design of APR requires that most APR types be incomplete. 153It is not possible to write flexible portable code if programs can access 154the internals of APR types. This is because different platforms are |
| 155likely to define different native types. There are only two execptions to | 155likely to define different native types. There are only two exceptions to |
| 156this rule:</p> 157 158<ul> 159<li>The first exception to this rule is if the type can only reasonably be 160implemented one way. For example, time is a complete type because there 161is only one reasonable time implementation. 162 163<li>The second exception to the incomplete type rule can be found in --- 58 unchanged lines hidden (view full) --- 222 * @param parma_n_name explanation 223 * @tip Any extra information people should know. 224 * @deffunc function prototype if required 225 */ 226</pre> 227 228<p>For an actual example, look at any file in the include directory. The 229reason the docs are in the header files is to ensure that the docs always | 156this rule:</p> 157 158<ul> 159<li>The first exception to this rule is if the type can only reasonably be 160implemented one way. For example, time is a complete type because there 161is only one reasonable time implementation. 162 163<li>The second exception to the incomplete type rule can be found in --- 58 unchanged lines hidden (view full) --- 222 * @param parma_n_name explanation 223 * @tip Any extra information people should know. 224 * @deffunc function prototype if required 225 */ 226</pre> 227 228<p>For an actual example, look at any file in the include directory. The 229reason the docs are in the header files is to ensure that the docs always |
| 230reflect the current code. If you change paramters or return values for a | 230reflect the current code. If you change parameters or return values for a |
| 231function, please be sure to update the documentation.</p> 232 233<h2>APR Error reporting</h2> 234 235<p>Most APR functions should return an ap_status_t type. The only time an 236APR function does not return an ap_status_t is if it absolutely CAN NOT 237fail. Examples of this would be filling out an array when you know you are 238not beyond the array's range. If it cannot fail on your platform, but it 239could conceivably fail on another platform, it should return an ap_status_t. 240Unless you are sure, return an ap_status_t.</p> 241 242<strong> 243 This includes functions that return TRUE/FALSE values. How that 244 is handled is discussed below 245</strong> 246 247<p>All platforms return errno values unchanged. Each platform can also have 248one system error type, which can be returned after an offset is added. | 231function, please be sure to update the documentation.</p> 232 233<h2>APR Error reporting</h2> 234 235<p>Most APR functions should return an ap_status_t type. The only time an 236APR function does not return an ap_status_t is if it absolutely CAN NOT 237fail. Examples of this would be filling out an array when you know you are 238not beyond the array's range. If it cannot fail on your platform, but it 239could conceivably fail on another platform, it should return an ap_status_t. 240Unless you are sure, return an ap_status_t.</p> 241 242<strong> 243 This includes functions that return TRUE/FALSE values. How that 244 is handled is discussed below 245</strong> 246 247<p>All platforms return errno values unchanged. Each platform can also have 248one system error type, which can be returned after an offset is added. |
| 249There are five types of error values in APR, each with it's own offset.</p> | 249There are five types of error values in APR, each with its own offset. |
| 250 251<!-- This should be turned into a table, but I am lazy today --> 252<pre> 253 Name Purpose 2540) This is 0 for all platforms and isn't really defined 255 anywhere, but it is the offset for errno values. 256 (This has no name because it isn't actually defined, 257 but for completeness we are discussing it here). --- 14 unchanged lines hidden (view full) --- 272 APR apps can begin to add their own error codes. 273 2743) APR_OS_START_SYSERR This is platform dependent, and is the offset at which 275 system error values begin. 276</pre> 277 278<strong>The difference in naming between APR_OS_START_ERROR and 279APR_OS_START_STATUS mentioned above allows programmers to easily determine if | 250 251<!-- This should be turned into a table, but I am lazy today --> 252<pre> 253 Name Purpose 2540) This is 0 for all platforms and isn't really defined 255 anywhere, but it is the offset for errno values. 256 (This has no name because it isn't actually defined, 257 but for completeness we are discussing it here). --- 14 unchanged lines hidden (view full) --- 272 APR apps can begin to add their own error codes. 273 2743) APR_OS_START_SYSERR This is platform dependent, and is the offset at which 275 system error values begin. 276</pre> 277 278<strong>The difference in naming between APR_OS_START_ERROR and 279APR_OS_START_STATUS mentioned above allows programmers to easily determine if |
| 280the error code indicates an error condition or a status codition. | 280the error code indicates an error condition or a status condition.</strong> |
| 281 282<p>If your function has multiple return codes that all indicate success, but 283with different results, or if your function can only return PASS/FAIL, you 284should still return an apr_status_t. In the first case, define one 285APR status code for each return value, an example of this is 286<code>apr_proc_wait</code>, which can only return APR_CHILDDONE, 287APR_CHILDNOTDONE, or an error code. In the second case, please return 288APR_SUCCESS for PASS, and define a new APR status code for failure, an --- 51 unchanged lines hidden (view full) --- 340<li> Return platform specific error codes and convert them when necessary. 341</ol> 342 343<p>The problem with option number one is that it takes time to convert error 344codes to a common code, and most of the time programs want to just output 345an error string. If we convert all errors to a common subset, we have four 346steps to output an error string:</p> 347 | 281 282<p>If your function has multiple return codes that all indicate success, but 283with different results, or if your function can only return PASS/FAIL, you 284should still return an apr_status_t. In the first case, define one 285APR status code for each return value, an example of this is 286<code>apr_proc_wait</code>, which can only return APR_CHILDDONE, 287APR_CHILDNOTDONE, or an error code. In the second case, please return 288APR_SUCCESS for PASS, and define a new APR status code for failure, an --- 51 unchanged lines hidden (view full) --- 340<li> Return platform specific error codes and convert them when necessary. 341</ol> 342 343<p>The problem with option number one is that it takes time to convert error 344codes to a common code, and most of the time programs want to just output 345an error string. If we convert all errors to a common subset, we have four 346steps to output an error string:</p> 347 |
| 348<p>The seocnd problem with option 1, is that it is a lossy conversion. For | 348<p>The second problem with option 1, is that it is a lossy conversion. For |
| 349example, Windows and OS/2 have a couple hundred error codes, but POSIX errno 350only defines about 50 errno values. This means that if we convert to a 351canonical error value immediately, there is no way for the programmer to 352get the actual system error.</p> 353 354<pre> 355 make syscall that fails 356 convert to common error code step 1 --- 43 unchanged lines hidden --- | 349example, Windows and OS/2 have a couple hundred error codes, but POSIX errno 350only defines about 50 errno values. This means that if we convert to a 351canonical error value immediately, there is no way for the programmer to 352get the actual system error.</p> 353 354<pre> 355 make syscall that fails 356 convert to common error code step 1 --- 43 unchanged lines hidden --- |