Apache数据结构主要分类和功能介绍

The Apache API is full of structures and routines; there are well over three hundred of them. However, for most purposes there are only five API structures that are really important. Some of them are so common and use the same naming convention so consistently that ou can easily tell what’s going on by looking at the variable names.

Apache API充满结构和例程;这里有超过三百个。然而,对于大多数情况下，只有5个API结构是非常重要的。他们中的一些是很常见的并且使用相同的命名,所以你可以很容易地通过观察变量的名字知道发生了什么。

Each of these structures are described in more detail later, but here are the Big Five: 这些结构在之后都将更详细地描述,但是在这里有五大结构:
· pool (usually pointed to by “p”) – a memory management structure pool(通常指“p”)——一个内存管理结构
· server_rec (usually pointed to by “s”) – contains information about a server or virtual host server_rec(通常指“s”)——包含关于服务器或虚拟主机的信息
· request_rec (usually pointed to by “r”) – defines the attributes of a client (or internal) request request_rec(通常指“r”)——定义了客户端(或内部)的属性的要求
· module – defines the callback hooks for your module and points to lists of directives and content handlers module——为您的模块定义了回调钩子和指向的指令列表和内容处理程序

· cmd_parms – used to convey information to a directive handler about the environment cmd_parms——用于向关于环境的指令处理程序传达信息

pool Structure 池结构

The pool structure is arguably the most important one in the entire API. A pool is a memory management structure with the following attributes: 池结构在整个API里可以说是最重要的一个。池是一个内存管理结构，具有以下属性:
· It may (or may not) have a parent 它可能有（或可能没有）父类。
· Memory can be allocated using either the ap_palloc() (allocate from pool) or ap_pcalloc() (allocate from pool and clear) routines 内存就可以利用apr_palloc（）（从池中分配）或apr_pcalloc（）（从池中分配和明确的）程序进行分配
· There is no free() function; pools grow until they’re destroyed 没有免费的()函数;池增长直到他们摧毁
· When a pool is destroyed, and and all sub-pools are recursively destroyed as well 当池被破坏，并且所有子池递归销毁
· When a pool is destroyed, any cleanup functions registered in it are invoked 池被摧毁时,任何注册的清理函数会被调用

Because of the highly dynamic nature of a Web server, handling a variable load of typically short-lived requests, the lack of a free() routine in the pool API is not a problem. Apache will allocate a pool when it begins processing a request, and all modules that deal with the request use that pool for their scrratch space. When the request has been completed, the pool is destroyed and everything is automatically cleaned up.

因为Web服务器高度动态特性,在处理大量短连接时，压力随时变化,池相关API中缺乏free()函数不是问题。开始处理请求时，Apache将分配一个池,当它开始处理请求，并使用所有模块以该池的暂存空间请求处理。当请求已经完成,池中被摧毁,一切都是自动清理。

Everything involves pools; other structures (such as the request_rec and server_rec) are allocated from them, pool-oriented string manipulation routines like ap_pstrcpy() and ap_pstrdup() are used in preference to their mundane counterparts, and malloc() and free() is strongly discouraged. Almost every single API routine has access to a pool, either through a pointer to one being explicitly in the argument list or by there being one inside one of the structures that is passed.

所有都涉及到池;其他结构(如request_rec server_rec)是从内存池中分配,基于池的字符串操作函数像ap_pstrcpy和和ap_pstrdup()鼓励使用，而malloc()和free()强烈反对。几乎每一个API程序能够访问一个池,通过一个指针指向一个明确的参数列表或有一个内部传递的结构。

Pools include what’s called a ‘cleanup’ mechanism. If you allocate structures from a pool and need to clean them up when the pool is destroyed (such as closing a database connexion or the like), you accomplish this by registering a cleanup in the pool. When the pool destruction code runs, it invokes any and all cleanup hooks it finds registered with it.

池包括所谓的“清理”机制。如果你从池中分配结构并且池销毁时需要清理(例如关闭数据库连接或类似的),你通过在池中注册一个清理结构做到这一点。当池销毁代码运行时,它调用并且清理所有它发现的注册。

The pool structure is completely opaque to modules, meaning that it has no fields or components that you need to access (and can’t even if you wanted to).
池模块结构是完全不透明的,这意味着它没有字段或组件需要访问(如果你想有也不能做到)。

Two other structures that are closely related to pools are Apache arrays and tables. Apache arrays are dynamically-sizable sequential lists of arbitrarily-sized elements; tables are key-value pairs (where both the key and the value must be strings). Both structures include a pool pointer, and additions to the array or table automatically results in memory being allocated from that pool at need.

池的两个密切相关的其他结构是Apache数组和表。Apache数组是长度动态调整顺序列表，列表内包含任意大小的元素;表是键值对(两个键和值必须是字符串)。两个结构体都包括一个池指针，超出数组或表大小，有需要则自动从池中重新分配。

server_rec Structure server_rec结构

Each global server and virtual host environment is defined in a server_rec structure. This includes things like information about the activity and error logs, timeout values, the server’s host name, pointers to lists of module configuration records, and so on. In most cases this structure should be considered “readonly” by modules, and in fact most modules don’t even care about the contents of the structure (unless they have directives with server-wide scope, of course).

每个全局服务器和虚拟主机环境中定义一个server_rec结构。这包括关于活动的信息和错误日志,超时值,服务器的主机名,指针模块配置列表记录,等等。在大多数情况下,在大多数情况下，这种结构应该被认为是“只读”的模块,其实大部分模块甚至不关心结构的内容（除非他们有与服务器范围的指令）。

For more information about this structure, see its definition in the src/include/httpd.h header file and the (rudimentary) <http://dev.apache.org/apidoc/> online API documentation. 有关此结构的详细信息，请参阅其在src/定义在include / httpd.h中头文件和（初级）http://dev.apache.org/apidoc/在线API文档。

request_rec Structure request_rec结构

Each client request for a URI (and each such request that the server may generate internally) is described by a request_rec structure. A request_rec consists mainly of pointers: a pool pointer, a pointer to a list of environment variables made available to CGI scripts and SSI documents (if that’s what the request resolves to), pointers to lists of HTTP request and response header fields, a pointer to the actual file name (if the request resolves to a file), and so on.

每个客户端请求URI(有一个个这样的请求,就有一个这样的结构，服务器会在内部分配产生)由request_rec结构描述。request_rec主要由指针组成:池的指针,一个指向环境变量列表指针提供给CGI脚本和SSI文档(如果请求解决),HTTP请求和响应头字段列表的指针,一个指向实际的文件名指针(如果请求解析为一个文件),等等。

Unlike the server_rec, the request_rec is most definitely a read/write structure from the module writer’s point of view. Most of the early request processing phases are transformations or interpretations of the information in the request_rec, and the results are likewise stored there for later use by the same or other modules.

从作者的观点来看，不同于server_rec,request_rec绝对是一个读/写的结构模块。大多数早期的请求处理阶段是转换，或在request_rec内信息的解释，其结果是存起来后续使用，使用者可以是同一模块，也可能不一样。

Requests may include an Apache concept called a subrequest. A subrequest is essentially a subordinate request the server makes internally, in order to answer a question about the current request. For example, in an SSI parsed document, each #include directive will result in a subrequest being made for the specified resource; this allows the server to either insert the content or an error message in the content of the main request it is constructing.

可能包括一个Apache的概念称为subrequest请求。一个子请求本质上是一个下属请求服务器内部,为了回答一个关于当前请求问题。例如,在一个SSI解析文档,每个#include指令将导致subrequest的指定资源;这允许服务器插入内容或错误消息主请求的内容里，这些内容组成了请求。

Subrequests differ from normal requests in that they are not automatically completed. That is, a module may fire off a subrequest for a file, and only be interested in the filled-in request_rec that results (such as the file statistics or the content type). 子请求不同于正常请求,他们不会自动完成。也就是说，一个模块可以触发关闭一个文件的子请求，并且只对填充好有结果request_rec感兴趣的（如文件的统计或内容类型）。

cmd_parms Structure cmd_parms结构

As far as module writers are concerned, the cmd_parms structure is only used when processing directives. It’s passed to the directive handler in the argument list, and include things such as the actual directive name, the full line being processed from the configuration source, the line number, a pool pointer for any structures the directive handler may need to allocation, the applicable limitations and overrides in effect, a pointer to the server_rec for the server in whose scope the directive was found, and so on. In most cases, the only thing used from this structure is the pool pointer.

对于模块的作者而言,cmd_parms结构只用于处理指令时。它传递到参数列表中的指令处理程序，包括诸如实际的指令名，从配置源处理好的整行，行号，任何结构的池指针（指示处理程序可能需要分配），限制及有效覆盖,服务器server_rec指针（服务器范围发现的指令）,等等。在大多数情况下,使用这种结构的唯一的办法就是指针。

module Structure 模块结构

As described earlier, the module structure provides the glue between the Apache server core code and the module itself. The server only knows about what it finds in the module structure, and no more. 如前面所述，该模块结构提供Apache服务器核心代码及模块本身之间的粘合剂。服务器只知道它在模块结构中发现了什么，并没有更多的信息。

Note: The MODULE_MAGIC_NUMBER (described later) is stored in the module structure at compile time. 注意:MODULE_MAGIC_NUMBER(稍后介绍)在编译时存储在模块结构

The module structure includes slots for pointers to all the possible callback hooks, some identification information, and pointers to lists of directives and content handler names. 模块结构包括用于指针的所有可能的回调挂钩，一些识别信息插槽，指令和内容处理名称的列表的指针。

You basically just set this structure up in your module source and just leave it alone; at run-time it’s a readonly structure.

你基本上只是源模块设置它，后续这个结构就不用管它;在运行时它是只读的结构。