這個指南主要介紹如何使用libapr（apache portable runtime）。
版權(quán)所有，Copyright (C) 2005 INOUE Seiichiro <inoue&ariel-networks.com>，翻譯：成彥
原文地址：http://dev.ariel-networks.com/apr/apr-tutorial/html/apr-tutorial.html
轉(zhuǎn)載時請保留版權(quán)信息。
大多數(shù)libapr的API都依賴于內(nèi)存池，借助內(nèi)存池，簡化了內(nèi)存塊的管理。想像一下沒有內(nèi)存池系統(tǒng)的情況：你申請一些內(nèi)存塊就必需逐個釋放它們，例如如果你申請了10個內(nèi)存塊，你必需釋放10次，否則，你將遭受內(nèi)存泄露的錯誤。內(nèi)存池解決了這個令人感到繁瑣的問題，在申請一個內(nèi)存池之后，你可以從內(nèi)存池中申請多個內(nèi)存塊，釋放它們的時候，你所需要做的就是銷毀內(nèi)存池，這樣你就可以釋放所有的內(nèi)存塊了。這有兩個優(yōu)點，第一，它可以預(yù)防內(nèi)存泄露的錯誤；第二，分配內(nèi)存塊的開銷相對變低了。從某種意義上說，內(nèi)存池迫使你遵循面向會話編程，一個內(nèi)存池就是一種會話內(nèi)容，這樣，處于同一個內(nèi)存池中的對象就有相同的生命周期，你可以通過控制會話內(nèi)容來控制對象。在一個會話的開始，你創(chuàng)建了一個內(nèi)存池，接著，你在內(nèi)存池中創(chuàng)建了一些對象，你不需要去關(guān)心這些對象的生命周期，最后，在會話結(jié)束的時候，你只需要將那個內(nèi)存池銷毀就可以了。
注：通常，對象生命周期控制是程序開發(fā)最困難的部分，因此，針對這個問題還存在有一些技術(shù)，例如智能指針，垃圾回收機制等等。需要注意，同時使用這些技術(shù)有一定的難度，內(nèi)存池也是這其中的一項技術(shù)，所以你不得不非常小心的使用它們。
注：在將來，libapr的內(nèi)存池將變得不再那么重要。參見http://mail-archives.apache.org/mod_mbox/apr-dev/200502.mbox/%3c1f1d9820502241330123f955f@mail.gmail.com%3e.
下面有三個基本的API函數(shù):
/* 摘自 apr_pools.h */
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);
我們使用apr_pool_create()函數(shù)創(chuàng)建一個內(nèi)存池，這個內(nèi)存池將一直存活，直到你調(diào)用apr_pool_destroy()函數(shù)以后被銷毀。apr_pool_create()的第一個參數(shù)是一個結(jié)果輸出參數(shù)，是一個新創(chuàng)建的apr_pool_t類型的內(nèi)存池對象。通過調(diào)用apr_palloc()來申請指定大小的內(nèi)存塊，具體使用方法見mp-sample.c。
/* 摘自 mp-sample.c */
apr_pool_t *mp;
/* 創(chuàng)建內(nèi)存池 */
apr_pool_create(&mp, NULL);
/* 從內(nèi)存池中分配內(nèi)存塊 */
char *buf1;
buf1 = apr_palloc(mp, MEM_ALLOC_SIZE);
簡單地說，我們可以像使用malloc(3)這樣使用apr_palloc()，也可以調(diào)用apr_pcalloc()，正如你猜到的，apr_pcalloc類似于calloc(3)，apr_pcalloc返回一個被0填充了的內(nèi)存塊。假如你使用了malloc(3)/calloc(3)，你需要調(diào)用free(3)來釋放分配了的內(nèi)存。但是在內(nèi)存池中，你必不需要釋放每個內(nèi)存塊，你只需要對該內(nèi)存池調(diào)用apr_poll_destroy()函數(shù)從而釋放所有的內(nèi)存塊。
注：使用apr_palloc()申請內(nèi)存，其內(nèi)存塊的大小沒有限制，然而，在內(nèi)存池中申請大內(nèi)存并不是什么好主意。內(nèi)存池本質(zhì)上是為了更小的內(nèi)存塊而設(shè)計的，實際上，初始的內(nèi)存池的大小是8000字節(jié)。如果你需要申請超過幾兆字節(jié)的內(nèi)存塊時，那么就不要使用內(nèi)存池。
注：默認情況下，內(nèi)存池管理器從不將申請到的內(nèi)存歸還給系統(tǒng)。如果程序要運行很長時間，這將是一個問題，推薦像下面的代碼那樣指定一個上限：
/* 設(shè)置上限，讓內(nèi)存池管理器釋放內(nèi)存，將內(nèi)存返回給系統(tǒng)的示例代碼 */
#define YOUR_POOL_MAX_FREE_SIZE 32 /* apr_pool max free list size */
apr_pool_t *mp;
apr_pool_create(&mp, NULL);
apr_allocator_t* pa = apr_pool_allocator_get(mp);
if (pa) {
apr_allocator_max_free_set(pa, YOUR_POOL_MAX_FREE_SIZE);
}
這兒有兩個API函數(shù)需要知道，一個是apr_pool_clear()，另一個是apr_pool_cleanup_register()，apr_pool_clear()類似于apr_pool_destroy()，不同的是內(nèi)存池將一直存在。示例代碼如下：
/* 使用apr_pool_clear()的例子 */
apr_pool_t *mp;
apr_pool_create(&mp, NULL);
for (i = 0; i < n; ++i) {
do_operation(..., mp);
apr_pool_clear(mp);
}
apr_pool_destroy(mp);
do_operation()里使用了內(nèi)存池，分配了一些內(nèi)存塊。假如在do_operation()之外不需要這些內(nèi)存塊了，可以調(diào)用apr_pool_clear()函數(shù)，這樣能縮小內(nèi)存的使用大小。如果你熟悉系統(tǒng)的棧內(nèi)存的話，你會覺得內(nèi)存池與棧內(nèi)存一樣，調(diào)用apr_palloc只是如同移動SP（棧指針），調(diào)用apr_pool_clear()如同重置SP，兩者都是輕量級的操作。
使用apr_pool_cleanup_register()函數(shù)，可以在內(nèi)存池清空/銷毀上設(shè)定一個鉤子（回調(diào)）函數(shù)，在內(nèi)存池清空或是銷毀后調(diào)用這個函數(shù)，在這個回調(diào)函數(shù)中，你可以實現(xiàn)任何在內(nèi)存池上的結(jié)束代碼。
關(guān)于內(nèi)存池的最后一個主題是子池，每個內(nèi)存池都可以有一個父內(nèi)存池，因此，內(nèi)存池構(gòu)造了樹。apr_pool_create()的第二個參數(shù)表示父內(nèi)存池，當這個參數(shù)為NULL時，新創(chuàng)建的內(nèi)存池將變?yōu)橐粋€根內(nèi)存池，可以在這個根內(nèi)存池上創(chuàng)建子內(nèi)存池。在這個樹中對一個內(nèi)存池調(diào)用apr_pool_destroy()函數(shù)，則該內(nèi)存池的子內(nèi)存池也將被銷毀；當對該內(nèi)存池調(diào)用apr_pool_clear()函數(shù)，則這個內(nèi)存池存在但是它的子內(nèi)存池將被銷毀，上面提及到的那些清除函數(shù)，在子內(nèi)存池銷毀時被調(diào)用。
注：當將NULL值做為清除回調(diào)函數(shù)時將會產(chǎn)生一個bug，你必須像下面的代碼那樣傳入apr_pool_cleanup_null：
/* 關(guān)于內(nèi)存池典型bug的偽代碼 */
/* apr_pool_cleanup_register(mp, ANY_CONTEXT_OF_YOUR_CODE, ANY_CALLBACK_OF_YOUR_CODE, NULL); 這將產(chǎn)生一個bug */
/* 修正： */
apr_pool_cleanup_register(mp, ANY_CONTEXT_OF_YOUR_CODE, ANY_CALLBACK_OF_YOUR_CODE, apr_pool_cleanup_null);