<!doctype linuxdoc system><article><title>libapr(apache portable runtime) programming tutorial</title><author>INOUE Seiichiro <tt><htmlurl url="mailto:inoue@ariel-networks.com"			      name="&lt;inoue@ariel-networks.com&gt;"></tt></author><date>2005/8/29</date><abstract>This is a tutorial on how to use libapr(apache portable runtime).</abstract><!-- Table of contents --><toc><sect>Tutorial Availability<p>Please look for updates on <htmlurl url="http://dev.ariel-networks.com/apr/" name="http://dev.ariel-networks.com/apr/">.<sect>libapr skeleton code<p>I believe it is a good idea to write 'skeleton code' at first, when you start to learn a new library or a new framework programming. 'skeleton code' is the smallest source code, but you can compile and execute it (although it usually do nothing useful).Fortunately, libapr's skeleton code is much simpler than other modern frameworks. Let's take a look at apr-skeleton.c. We call apr_initialize() at the initialization, and call apr_terminate() at the finalization. That's all. As you can imagine, the code does nothing.libapr is not a framework library. Accordingly, libapr doesn't help you to design the whole structure of the source code. There are pros and cons. Pros is that it is easy to use libapr with the other existing code. Cons is that you need to design the whole structure of the code by yourself when you use libapr. Here, we have some libapr programming styles and rules:<itemize><item>naming rule is very simple and clear.</item><item>opaque data types are commonly used (a.k.a. incomplete types)</item><item>most of return types are apr_status_t. As a result, result-arguments are commonly used.</item><item>memory pool rules</item></itemize>We are able to see these styles in the following code./* excerpted from <htmlurl url="../sample/mp-sample.c" name="mp-sample.c"> */<tscreen><verb>apr_status_t rv;apr_pool_t *mp;rv = apr_pool_create(&amp;mp, NULL);</verb></tscreen>I will describe the meaning of the code. Here, please take a look at only style. You can see apr_ prefix. The apr_ prefix indicates that the symbol is in libapr naming scope. You can see _t suffix. It indicates that the symbol is a type name.apr_pool_t is opaque type. It means the type's structure is not public. By OO(Object Oriented) terminology, all member variables are private. You can't touch them directly. Furthermore, you can't see them in public header files. All you can do for the type is to call APIs such as apr_foo_bar() functions. Most importantly, you can't allocate their instance memories directly. All you can do is to call construct APIs. Only libapr knows how to construct and destruct the objects.As you see, apr_pool_create()'s return type is apr_status_t. apr_status_t is either status code or error code. apr_status_t is a commonly used as return types of most APIs. Accordingly, we can get results from functions by arguments. Such arguments are called result-argument. There are many result-arguments in the libapr world.In general, if you see apr_foo_t type, you will see apr_foo_bar() functions, which are related to apr_foo_t type.The following code is a typical pseudo code.<tscreen><verb>/* pseudo code of libapr. error checks omitted */apr_status_t rv;apr_foo_t *foo;rv = apr_foo_create(&amp;foo, args...);/* create a @foo object by @args */rv = apr_foo_do_something(foo, args...); /* do something with @foo */apr_foo_destroy(foo); /* destroy the @foo object. Sometimes, this is done implicitly by destroying related memory pool. Please see below */</verb></tscreen><sect>memory pool (apr_pool_t)<p>Most of libapr APIs are dependent on memory pool. By memory pool, you can easily manage a set of memory chunks. Imagine the case without memory pool system, where you allocate several memory chunks. You have to free each of them. If you have ten memory chunks, you have to free ten times, otherwise you would suffer from memory leak bugs.Memory pool solves this issue. After you allocate one memory pool, you can allocate multiple memory chunks from the pool. To free them, all you have to do is to destroy the memory pool. By which, you can free all the memory chunks. There are two good points. First, as stated above, it is defensive against memory leak bugs. Second, allocation costs of memory chunks become relatively lower. In a sense, memory pool forces you to obey a session-oriented programming. A memory pool is a kind of a session context, that is, a set of objects that have the same lifetimes. You can control a set of objects within a session context. At the beginning of a session you create a memory pool. Then, you create objects in the memory pool during the session. Note that you don't need to care about their lifetimes. Finally, at the end of the session all you have to do is to destroy the memory pool.<em>REMARK</em>: In general, objects lifetime control is the most difficult part in programming. Thus, there are many other techniques for it, such as smart pointer, GC(garbage collection) and so on. Note that it is a bit hard to use such techniques at the same time. Since memory pool is one of such techniques, you have to be careful about the mixture.<em>REMARK</em>: In the future, memory pool would become less important than now in libapr. Please refer to <htmlurl url="http://mail-archives.apache.org/mod_mbox/apr-dev/200502.mbox/%3c1f1d9820502241330123f955f@mail.gmail.com%3e" name="http://mail-archives.apache.org/mod_mbox/apr-dev/200502.mbox/%3c1f1d9820502241330123f955f@mail.gmail.com%3e">.There are three basic APIs as follows:/* excerpted from apr_pools.h */<tscreen><verb>APR_DECLARE(apr_status_t) apr_pool_create(apr_pool_t **newpool,                                          apr_pool_t *parent);APR_DECLARE(void *) apr_palloc(apr_pool_t *p, apr_size_t size);APR_DECLARE(void) apr_pool_destroy(apr_pool_t *p);</verb></tscreen>We create a memory pool by apr_pool_create(). The memory pool is alive until you call apr_pool_destroy(). The first argument of apr_pool_create() is a result argument. A newly created memory pool object, apr_pool_t, is returned by this API call. We call apr_palloc() to get a memory chunk by specifing the chunk's size. Please take a look at <htmlurl url="../sample/mp-sample.c" name="mp-sample.c"> to know the usage./* excerpted from <htmlurl url="../sample/mp-sample.c" name="mp-sample.c"> */<tscreen><verb>apr_pool_t *mp;/* create a memory pool. */apr_pool_create(&amp;mp, NULL);/* allocate memory chunks from the memory pool */char *buf1;buf1 = apr_palloc(mp, MEM_ALLOC_SIZE);</verb></tscreen>In a nutshell, we can use apr_palloc() like malloc(3). We can also call apr_pcalloc(). As you can guess, apr_pcalloc() is similar to calloc(3). apr_pcalloc() returns a zero-cleard memory chunk. If you use malloc(3)/calloc(3), you need to call free(3) for the allocated memories. In contrast, you don't need to free each memory chunks in memory pool. You just call apr_pool_destroy() for the memory pool and it frees all the memory chunks.<em>REMARK</em>: There is no limitation about memory chunk size that you can allocate by apr_palloc(). Nevertheless, it isn't a good idea to allocate large size memory chunk in memory pool. That is because memory pool is essentially designed for smaller chunks. Actually, the initial size of memory pool is 8 kilo bytes. If you need a large size memory chunk, e.g. over several mega bytes, you shouldn't use memory pool.<em>REMARK</em>: By default, memory pool manager never returns allocated memory back to the system. If a program runs for a long time, it would have problem. I recommend you to specify the upper limit as follows:<tscreen><verb>/* sample code to set the upper limit to make memory pool manager release the memory back to the system */#define YOUR_POOL_MAX_FREE_SIZE	32	/* apr_pool max free list size */apr_pool_t *mp;apr_pool_create(&amp;mp, NULL);apr_allocator_t* pa = apr_pool_allocator_get(mp);if (pa) {    apr_allocator_max_free_set(pa, YOUR_POOL_MAX_FREE_SIZE);}</verb></tscreen>    There are two more APIs you have to know. One is apr_pool_clear(), and the other is apr_pool_cleanup_register(). apr_pool_clear() is similar to apr_pool_destroy(), but the memory pool is still reusable. A typical code is as follows:<tscreen><verb>/* sample code about apr_pool_clear() */apr_pool_t *mp;apr_pool_create(&amp;mp, NULL);for (i = 0; i < n; ++i) {    do_operation(..., mp);    apr_pool_clear(mp);}apr_pool_destroy(mp);</verb></tscreen>The memory pool is used in do_operation(), that is, several memory chunks are allocated. If you don't need the memory chunks out of do_operation(), you can call apr_pool_clear(). You are able to reduce the amount of memory usage. If you are familiar with local stack memory system, you can think of memory pool as local stack memory. Calling apr_palloc() is similar to moving SP(stack pointer), and calling apr_pool_clear() is similar to rewinding SP. Both are very light operations.By apr_pool_cleanup_register(), we can have hook functions on memory pool clear/destroy. You have a callback function that is called whenever the memory pool is cleared or destroyed. In the callback functions, you can implement any finalization code depending on the memory pool.The last topic about memory pool is sub pool. Each memory pool is able to have a parent memory pool. Accordingly, memory pools construct trees. The second argument of apr_pool_create() is a parent memory pool. When you pass NULL as the parent memory pool, the newly created memory pool becomes a root memory pool. You can create sub memory pools under the root memory pool. Whene you call apr_pool_destroy() for a memory pool in the tree, the child memory pools are also destroyed. When you call apr_pool_clear() for the memory pool, the memory pool is alive but the child memory pools are destroyed. Whenever a child memory pool is destroyed, the cleanup functions for it mentioned above are called.<em>REMARK</em>: It is a typical bug that you pass NULL as pool cleanup callback function. Instead, you must pass apr_pool_cleanup_null as follows:<tscreen><verb>/* pseudo code about memory pool typical bug *//* apr_pool_cleanup_register(mp, ANY_CONTEXT_OF_YOUR_CODE, ANY_CALLBACK_OF_YOUR_CODE, NULL); THIS IS A BUG *//* FIXED */apr_pool_cleanup_register(mp, ANY_CONTEXT_OF_YOUR_CODE, ANY_CALLBACK_OF_YOUR_CODE, apr_pool_cleanup_null);</verb></tscreen><sect>Error status (apr_status_t)<p>Most of libapr functions return apr_status_t value. apr_status_t value is each of APR_SUCCESS or the others. APR_SUCCESS just indicates success. A typical code looks as follows:<tscreen><verb>/* pseudo code about apr_status_t check */apr_status_t rv;rv = apr_pool_create(&amp;mp, NULL);if (rv != APR_SUCCESS) {   ERROR-HANDLING;}</verb></tscreen>libapr defines some error statuses such as APR_EINVAL, and some error-check macros such as APR_STATUS_IS_ENOMEM((). Some of them are rather useful on handling portability issues. A typical one is APR_STATUS_IS_EAGAIN() macro. Historically, there are two error numbers that have the same meaning, EAGAIN and EWOULDBLOCK. APR_STATUS_IS_EAGAIN() macro takes care of the issue. Nevertheless, it is almost impossible to deal with all error cases independently from many OSes. libapr doesn't reinvent the wheel on error handling. All libapr does is very simple.<itemize><item>In success, return APR_SUCCESS</item><item>In libapr layer's error, return APR_FOO error code</item><item>In very common OS error, return APR_FOO error code</item><item>In most of OS dependent error, return OS error number with the offset</item></itemize>I recommend you to follow the simple rules.<itemize><item>To compare return value with APR_SUCCESS</item><item>If you need to know more error details, to compare the values with the other error code</item></itemize>One API that you had better know is apr_strerror(). You can show the error description as follows:<tscreen><verb>/* pseudo code about apr_strerror() */apr_status_t rv;rv = apr_foo_bar();if (rv != APR_SUCCESS) {   char errbuf[256];   apr_strerror(rv, buf, sizeof(buf));   puts(errbuf);  /* show the error description */}</verb></tscreen><sect>file handling<p>