1.1 何為APR? APR(Apache portable Run-time libraries，Apache可移植運(yùn)行庫(kù))的目的如其名稱一樣，主要為上層的應(yīng)用程序提供一個(gè)可以跨越多操作系統(tǒng)平臺(tái)使用的底層支持接口庫(kù)。在早期的Apache版本中，應(yīng)用程序本身必須能夠處理各種具體操作系統(tǒng)平臺(tái)的細(xì)節(jié)，并針對(duì)不同的平臺(tái)調(diào)用不同的處理函數(shù)。隨著Apache的進(jìn)一步開發(fā)，Apache組織決定將這些通用的函數(shù)獨(dú)立出來(lái)并發(fā)展成為一個(gè)新的項(xiàng)目。這樣，APR的開發(fā)就從Apache中獨(dú)立出來(lái)，Apache僅僅是使用APR而已。目前APR主要還是由Apache使用，不過(guò)由于APR的較好的移植性，因此一些需要進(jìn)行移植的C程序也開始使用APR，開源項(xiàng)目比如Flood loader tester(http://httpd-apache-org/test/flood/，該項(xiàng)目用于服務(wù)器壓力測(cè)試，不僅僅適用于Apache)、FreeSwitch(www-freeswitch-org)，JXTA-C(http://jxta-c-jxta-org,C版本的JXTA點(diǎn)對(duì)點(diǎn)平臺(tái)實(shí)現(xiàn))；商業(yè)的項(xiàng)目則包括Blogline(http://www-bloglines-com/，covalent(http://www-covalent-net)等等。 APR使得平臺(tái)細(xì)節(jié)的處理進(jìn)行下移。對(duì)于應(yīng)用程序而言，它們根本就不需要考慮具體的平臺(tái)，不管是Unix、Linux還是Window，應(yīng)用程序執(zhí)行的接口基礎(chǔ)都是統(tǒng)一一致的。因此對(duì)于APR而言，可移植性和統(tǒng)一的上層接口是其考慮的一個(gè)重點(diǎn)。而APR最早的目的并不是如此，它最早只是希望將Apache中用到的所有代碼合并為一個(gè)通用的代碼庫(kù)，然而這不是一個(gè)正確的策略，因此后來(lái)APR改變了其目標(biāo)。有的時(shí)候使用公共代碼并不是一件好事，比如如何將一個(gè)請(qǐng)求映射到線程或者進(jìn)程是平臺(tái)相關(guān)的，因此僅僅一個(gè)公共的代碼庫(kù)并不能完成這種區(qū)分。APR的目標(biāo)則是希望安全合并所有的能夠合并的代碼而不需要犧牲性能。 APR的最早的一個(gè)目標(biāo)就是為所有的平臺(tái)(不是部分)提供一個(gè)公共的統(tǒng)一操作函數(shù)接口，這是一個(gè)非常了不起的目的，當(dāng)然也是不現(xiàn)實(shí)的一個(gè)目標(biāo)。我們不可能支持所有平臺(tái)的所有特征，因此APR目前只能為大多數(shù)平臺(tái)提供所有的APR特性支持，包括Win32、OS/2、BeOS、Darwin、Linux等等。為了能夠?qū)崿F(xiàn)這個(gè)目標(biāo)，APR開發(fā)者必須為那些不能運(yùn)行于所有平臺(tái)的特性創(chuàng)建了一系列的特征宏(FEATURE MACROS)以在各個(gè)平臺(tái)之間區(qū)分這些特征。這些特征宏定義非常簡(jiǎn)單，通常如下： APR_HAS_FEATURE 如果某個(gè)平臺(tái)具有這個(gè)特性，則該宏必須設(shè)置為true，比如Linux和window都具有內(nèi)存映射文件，同時(shí)APR提供了內(nèi)存映射文件的操作接口，因此在這兩個(gè)平臺(tái)上，APR_HAS_MMAP宏必須設(shè)置，同時(shí)ap_mmap_*函數(shù)應(yīng)該將磁盤文件映射為內(nèi)存并返回適當(dāng)?shù)臓顟B(tài)碼。如果你的操作系統(tǒng)并不支持內(nèi)存映射，那么APR_HAS_MMAP必須設(shè)置為0，而且所有的ap_mmap_*函數(shù)也可以不需要定義。第二步就是對(duì)于那些在程序中使用了不支持的函數(shù)必須提出警告。目前APR中支持的基礎(chǔ)類型包括下面幾種：表3-1 APR中支持的基礎(chǔ)類型

類型名稱	文件夾名稱	描述
atomic	/srclib/apr/atomic	原子操作
dso	/srclib/apr/dso	動(dòng)態(tài)加載共享庫(kù)
file io	/srclib/apr/file_io	文件IO處理
mmap	/srclib/apr/mmap	內(nèi)存映射文件
locks	/srclib/apr/locks	進(jìn)程和線程互斥鎖
memory	/srclib/apr/memory	內(nèi)存池操作
network_io	/srclib/apr/network_io	網(wǎng)絡(luò)IO處理
poll	/srclib/apr/poll	輪詢IO
table	/srclib/apr/tables	Apache數(shù)組(堆棧)和表格以及哈希表
process	/srclib/apr/threadproc	進(jìn)程和線程操作
user	/srclib/apr/user	用戶和用戶組操作
time	/srclib/apr/time	時(shí)間操作
string	/srclib/apr/strings	字符串操作
password	/srclib/apr/passwd	終端密碼處理
misc	/srclib/apr/misc	大雜燴，不屬于其余類的任何apr類型都可以放在里面
shmem	/srclib/apr/shmem	共享內(nèi)存
random	/srclib/apr/random	隨機(jī)數(shù)生成庫(kù)

每一個(gè)APR的實(shí)現(xiàn)我們都在后面會(huì)詳細(xì)描述。 1.2 APR版本規(guī)則由于Apache組織的目標(biāo)是將APR獨(dú)立出來(lái)形成單獨(dú)的第三方庫(kù)，因此對(duì)其而言穩(wěn)定的API接口就成為一個(gè)非常重要的必須考慮的方面。不過(guò)由于APR需要不斷的往前方展，因此API接口的變化又是必然的趨勢(shì)，因此如何平衡穩(wěn)定性和變化性是APR開發(fā)者面臨的一個(gè)極需解決的問(wèn)題。為此APR采用了嚴(yán)格的版本規(guī)則來(lái)實(shí)現(xiàn)這一點(diǎn)。用戶只需要簡(jiǎn)單的判斷APR版本號(hào)，就可以很容易確定當(dāng)前版本的兼容性：向前兼容、向后兼容還是前后同時(shí)兼容。 1.2.1版本概述 APR中使用三個(gè)整數(shù)來(lái)記錄APR版本號(hào)：MAJOR.MINOR.PATCH。MAJOR表示當(dāng)前APR的主版本號(hào)，它的變化通常意味著APR的巨大的變化，比如體系結(jié)構(gòu)的重新設(shè)計(jì)，API的重新設(shè)計(jì)等等，而且這種變化通常會(huì)導(dǎo)致APR版本的向前不兼容。MINOR稱之為APR的次版本號(hào)，它通常只反映了一些較大的更改，比如APR的API的增加等等，但是這些更改并不影響與舊版本源代碼和二進(jìn)制代碼之間的兼容性。PATCH通常稱之為補(bǔ)丁版本，通常情況下如果只是對(duì)APR函數(shù)的修改而不影響API接口的話都會(huì)導(dǎo)致PATCH的變化。目前為止APR的最高版本是1.2.2，最早遵循這種規(guī)則的版本號(hào)是0.9.0，不過(guò)在0.9.0之前，APR還推出了兩個(gè)版本a8和a9。不過(guò)有一點(diǎn)需要注意的是，我們后面描述的版本規(guī)則并不適合1.0.0以前的版本。對(duì)于1.0.0以前的版本(0.x.y)，APR提供的API是可以任意的改變而沒有任何的限制，因此這些版本的變化不遵循后面描述的版本規(guī)則。從1.0.0以后的所有版本都遵循。切記。除非主版本號(hào)發(fā)生變化，否則如果某個(gè)應(yīng)用程序使用了低版本的APR，那么如果將該版本用高版本的APR替代，應(yīng)用程序必須能夠無(wú)錯(cuò)誤的編譯通過(guò)，通常我們稱之為前向兼容行；反之很明顯，如果應(yīng)用程序中使用了高版本的APR，那么如果將該版本用低版本的APR替代，則未必能夠編譯通過(guò)，通常我們稱之為后向不兼容。 APR的發(fā)展中力圖總是保持與舊版本的源代碼和二進(jìn)制版本之間的兼容性。通過(guò)源代碼兼容，應(yīng)用程序就可以在使用新版本的APR進(jìn)行編譯的時(shí)候不會(huì)報(bào)錯(cuò)，這樣應(yīng)用程序就不需要為了適應(yīng)新的APR而做出調(diào)整，從而保持應(yīng)用開發(fā)的一致性和持續(xù)性。除非APR的主版本號(hào)發(fā)生變更。這種兼容性反之則不成立。如果一個(gè)應(yīng)用程序使用較高的MINOR版本開發(fā)，那么很明顯，如果將該版本替換為MINOR相對(duì)較低的版本進(jìn)行編譯，則成功的可能性應(yīng)該不是很大。除了源代碼方面的兼容性，APR還希望能夠保持二進(jìn)制之間的兼容性。通過(guò)保持二進(jìn)制兼容，應(yīng)用程序可以直接使用高版本的APR庫(kù)(或者是DLL，或者使so文件)替換低版本的庫(kù)文件，而不需要做任何修改，就可以鏈接成功。與源代碼兼容一樣，二進(jìn)制的兼容也是向前兼容，而不保證向后兼容。下面的表格演示了APR的版本規(guī)則策略：

原始版本	新版本	兼容性	原因
2.2.3	2.2.4	前后兼容	PATCH版本號(hào)的變化保持前向和后向兼容
2.2.3	2.2.1	前后兼容	PATCH版本號(hào)的變化保持前向和后向兼容
2.2.3	2.3.1	向前兼容	次版本號(hào)的變化保持向前兼容，但并不保持向后兼容
2.2.3	2.1.7	不兼容	次版本號(hào)的降低不能保證向后兼容
2.2.3	3.0.0	不兼容	主版本號(hào)的變化不保證兼容性
2.2.3	1.4.7	不兼容	主版本號(hào)的變化不保證兼容性

1.2.2版本策略為了控制APR接口的穩(wěn)定，APR制定了嚴(yán)格的版本變化策略。 1.2.2.1PATCH版本策略在前表中我們看到，PATCH的變化并不影響版本的源代碼和二進(jìn)制級(jí)別的兼容性，包括向前和向后兼容，因此，我們很容易看出，PATCH版本變化通常意味著對(duì)版本的修修補(bǔ)補(bǔ)，即BUG的修復(fù)。這些工作通常被局限于函數(shù)內(nèi)部的修改，或者是API函數(shù)內(nèi)部，或者是APR內(nèi)部static函數(shù)的變化。任何對(duì)API的增加、修改、刪除都是不允許的。 1.2.2.1次版本號(hào)策略任何新函數(shù)，新變量以及新常量的引入以及任何現(xiàn)有函數(shù)的廢除都將可能導(dǎo)致次版本號(hào)的變化： 1)、新函數(shù)的引入 An application coded against an older minor release will still have all of its functions available with their original signatures. Once an application begins to use a new function, however, they will be unable to work against older minor versions. It is tempting to say that introducing new functions might create incompatibility across minor releases. If an application takes advantage of an API that was introduced in version 2.3 of a library, then it is not going to work against version 2.2. However, we have stated that an any application built against version 2.2 will continue to work for all 2.x releases. Thus, an application that states "requires 2.3 or later" is perfectly acceptable -- the user or administrator simply upgrades the installed library to 2.3. This is a safe operation and will not break any other application that was using the 2.2 library. In other words, yes an incompatibility arises by mandating that a specific version needs to be installed. But in practice, this will not be a problem since upgrading to newer versions is always safe. 2)、新常量的引入 Similar to functions, all of the original (old) constants will be available to an application. An application can then choose to use new constants to pick up new semantics and features. 3)、函數(shù)替換 This gets a bit trickier. The original functionmustremain available at the link-level so that an application compiled against a minor version will continue to work with later minor versions. Further, if an application isdesignedto work with an earlier minor version, then we don't want to suddenly change the requirements for that application. This means that the headers cannot silently map an old function into a newer function, as that would turn an application, say, based on 1.2 into an application requiring the 1.4 or later release. This means that functions cannot truly be replaced. The new, alternate function can be made available in the header and applications can choose to use it (and become dependent upon the minor release where the function appears). It is possible to design a set of headers where a macro will always refer to the "latest" function available. Of course, if an application chooses to use this macro, then the resulting compiled-binary will be dependent upon whatever version it was compiled against. This strategy adds the new functionality for applications, yet retains the necessary source and binary compatibility for applications designed or built against previous minor releases. Constants (enumerated values and preprocessor macros) arenotallowed to change since an older application will still be using them. Similarly, function signatures at the link-level may not change, so that support for older, compiled applications is maintained. 4)、函數(shù)作廢隨著APR的升級(jí)，APR中的一些API可能將作廢，不再使用，但是這些API并不能從APR庫(kù)中移除。因?yàn)橐坏〢PI被移除，向后兼容性將被破壞。因此我們能夠做的僅僅是宣布其作廢。 If you deprecate a function in APR, please mark it as such in the function documentation, using the doxygen "\deprecated" tag. Deprecated functions can only be removed in major releases. A deprecated function should remain availablethroughthe original header. The function prototype should remain in the same header, or if moved to a "deprecated functions" header, then the alternate header should be included by the original header. This requirement is to ensure that source compatibility is retained.   Finally, if you are deprecating a function so that you can change the name of the function, please use the method described above under "Replacing functions", so that projects which use APR can retain binary compatibility. Note that all deprecated functions will be removed at the next major version bump. 1.2.2.3主版本號(hào)策略下面的任何一種變化都將可能導(dǎo)致主版本號(hào)的變化： 1)、常量的移除或者更改 2)、函數(shù)移除或者作為 3)、fold together macro-ized function replacements 1.2.3版本檢查由于APR嚴(yán)格的版本控制策略，使得應(yīng)用程序在使用APR庫(kù)之前必須能夠檢測(cè)使用的APR庫(kù)的版本號(hào)。APR允許在編譯以及使用APR的時(shí)候檢測(cè)它的版本號(hào)。 1.2.3.1 編譯時(shí)版本檢查 Libraries should make their version number available as compile-time constants. For example: #define FOO_MAJOR_VERSION 1 #define FOO_MINOR_VERSION 4 #define FOO_PATCH_VERSION 0 The above symbols are the minimum required for this specification. An application that desires, at compile-time, to decide on whether and how to use a particular library feature needs to only check two values: the major and the minor version. Since, by definition, there are no API changes across patch versions, that symbol can be safely ignored. Note that any kind of a check for a minimum version will then pin that application to at least that version. The application's installation mechanism should then ensure that that minimal version has been installed (for example, using RPM dependency checks). If the feature changes across minor versions are source compatible, but are (say) simply different choices of values to pass into the library, then an application can support a wider variety of installed libraries if it avoids compile-time checks. 1.2.3.2 執(zhí)行時(shí)版本檢查 A library meeting this specification should support a way for an application to determine the library's version atrun-time. This will usually be emboded as a simple function which returns the MAJOR, MINOR, and PATCH triplet in some form. Run-time checks are preferable in all cases. This type of check enables an application to run against a wider variety of minor releases of a library (the application is "less coupled" to a particular library release). Of course, if an application requires a function that was introduced in a later, minor release, then the application will require that, at least, that release is installed on the target system. Run-time checks are particurly important if the application is trying to determine if the library has a particular bug that may need to be worked around, but has been fixed in a later release. If the bug is fixed in a patch release, then the only avenue for an application is to perform a runtime check. This is because an application cannot require a specific patch level of the library to be installed -- those libraries are perfectly forward and backwards compatible, and the administrator is free to choose any patch release, knowing that all applications will continue to function properly. If the bug was fixed in a minor release, then it is possible to use a compile-time check, but that would create a tighter coupling to the library. 1.2.3.3 版本API 與前面的版本規(guī)則定義一致，APR中定義了數(shù)據(jù)結(jié)構(gòu)apr_version_t來(lái)描述版本規(guī)則： typedef struct {     int major;      /**< major number */     int minor;      /**< minor number */     int patch;      /**< patch number */     int is_dev;     /**< is development (1 or 0) */ } apr_version_t; major是當(dāng)前APR版本的主版本號(hào)，minor則是次版本號(hào)，patch對(duì)應(yīng)的則是APR的補(bǔ)丁號(hào)。es_dev則描述了當(dāng)前APR庫(kù)的狀態(tài)：開發(fā)版還是發(fā)行版，分別對(duì)應(yīng)1和0。一旦定義了apr_version_t結(jié)構(gòu)，APR就將使用它作為基礎(chǔ)的版本控制單位。APR中提供了函數(shù)apr_version和apr_version_string分別設(shè)置和返回APR的版本。 APR_DECLARE(void) apr_version(apr_version_t *pvsn) {     pvsn->major = APR_MAJOR_VERSION;     pvsn->minor = APR_MINOR_VERSION;     pvsn->patch = APR_PATCH_VERSION; #ifdef APR_IS_DEV_VERSION     pvsn->is_dev = 1; #else     pvsn->is_dev = 0; #endif } apr_version函數(shù)僅僅就是設(shè)置apr_version_t結(jié)構(gòu)中的各個(gè)成員。對(duì)于每一個(gè)APR版本，APR都會(huì)將當(dāng)前的版本號(hào)分別用三個(gè)常量定義在version.h中，比如，如果版本號(hào)是2.2.0，則常量定義應(yīng)該如下： #define APR_MAJOR_VERSION       2 #define APR_MINOR_VERSION       2 #define APR_PATCH_VERSION       0 apr_version_string函數(shù)僅僅是返回APR_VERSION_STRING宏，該宏定義為： #define APR_VERSION_STRING \      APR_STRINGIFY(APR_MAJOR_VERSION) "." \      APR_STRINGIFY(APR_MINOR_VERSION) "." \      APR_STRINGIFY(APR_PATCH_VERSION) \      APR_IS_DEV_STRING APR_STRINGIFY用于將給定的數(shù)值轉(zhuǎn)換為字符串，因此APR_VERSION_STRING宏就是無(wú)非將APR_MAJOR_VERSION，APR_MINOR_VERSION，APR_PATCH_VERSION分別轉(zhuǎn)換為字符串，再用"."連接起來(lái)，最后的形式應(yīng)該為“2.2.0”。盡管一般情況下，APR的版本號(hào)是“x.x.x”的格式，不過(guò)在Window的資源文件.rc中通常是“x,x,x”格式，因此APR中也提供了APR_VERSION_STRING_CSV來(lái)提供這種格式的版本號(hào)： #define APR_VERSION_STRING_CSVAPR_MAJOR_VERSION ##, \                              ##APR_MINOR_VERSION##, \                              ##APR_PATCH_VERSION ##宏用于將變量與特定字符進(jìn)行連接形成新的字符串。在后面的部分，我們會(huì)不斷看到它的用法。在一些情況下，應(yīng)用程序需要使用的APR版本達(dá)到一定的版本號(hào)，為此，APR中提供了APR_VERSION_AT_LEAST宏用以檢測(cè)給定的APR庫(kù)是否達(dá)到給定的版本要求： #define APR_VERSION_AT_LEAST(major,minor,patch)                    \ (((major) < APR_MAJOR_VERSION)                                     \  || ((major) == APR_MAJOR_VERSION && (minor) < APR_MINOR_VERSION) \  || ((major) == APR_MAJOR_VERSION && (minor) == APR_MINOR_VERSION && (patch) <= APR_PATCH_VERSION)) 如果我們希望當(dāng)前使用的APR庫(kù)的版本不的低于”1.2.0”，那么我們就使用使用APR_VERSION_AT_LEAST(1,2,0)對(duì)當(dāng)前的APR庫(kù)版本進(jìn)行檢查。

關(guān)鍵字：Apache APR 可移植 運(yùn)行庫(kù)

【 頂部 】 【 關(guān)閉 】