Changes between Version 45 and Version 46 of ModParrotArchitecture

Show
Ignore:
Timestamp:
12/05/08 19:12:14 (13 years ago)
Author:
jhorwitz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ModParrotArchitecture

    v45 v46  
    122122   * {{{void *csd}}} 
    123123 * {{{int module_index}}} - identifies the current HLL module (index into the server configuration's module_array) 
    124  * {{{int pool_index}}} - index into the context pool array 
    125124 
    126125The block of Apache data structures lists all possible structures that Apache may pass to a handler.  As a rule, if any of the Apache data structures are in scope, mod_parrot MUST update the corresponding pointer in the context before calling a metahandler.  This ensures that metahandlers can access the proper data structures, as they are given only the context to work with. 
     
    128127=== Context Pools === 
    129128 
    130 Contexts are allocated from context pools, which are populated at startup and tuned dynamically at runtime.  There is a single global pool, plus one pool per virtual host configured with {{{+Parent}}}. Virtual hosts without {{{+Parent}}} share the global pool.  Contexts contain pointers to Parrot interpreters so this also provides mod_parrot with a pool of interpreters.  Contexts are aware of their slot in the pool array (see {{{pool_index}}}). 
     129Contexts are allocated from context pools, which are populated at startup and tuned dynamically at runtime.  There is a single global pool, plus one pool per virtual host configured with {{{+Parent}}}. Virtual hosts without {{{+Parent}}} share the global pool.  Contexts contain pointers to Parrot interpreters so this also provides mod_parrot with a pool of interpreters. 
    131130 
    132131=== Context Lifecycle === 
    133132 
    134 Contexts are created at Apache startup during the configuration phase, when interpreters are needed to register various HLL modules and parse directives.  An interpreter is always started when a context is created. 
     133Contexts are created at Apache startup during the configuration phase, when interpreters are needed to register various HLL modules and parse directives.  An interpreter is always started when a context is created.  They are destroyed when an Apache process exits (XXX update for MaxSpareServers, etc.) 
    135134 
    136135Child processes in forking MPMs inherit (via {{{fork()}}}) the context pools created at startup, saving both CPU cycles and memory. 
    137136 
    138 To maintain state, the same context must be used for all phases of a request, as it contains a reference to the interpreter.  When a context is needed, code should call {{{init_ctx(server_rec *s, conn_rec *c)}}}, which will return an available context from the pool.  If {{{c}}} is non-null, {{{init_ctx}}} will either return the context bound to that connection, or bind and return an available context if none is already bound.  Code in hooks that run before the pre-connection phase should pass a NULL connection. 
    139  
    140 When a context is in use, it is locked behind the scenes by {{{reserve_ctx}}}.  While code should not call this function directly, it MUST call {{{release_ctx}}} after each phase is complete to unlock the context.  This may change in the future, as connection binding requires the use of the same context, so all this locking and unlocking is just overhead. 
    141  
    142 When the request/connection is complete, it is unlocked and disassociated from the connection by {{{modparrot_conn_cleanup}}}, a connection-scope pool cleanup handler.  
     137To maintain state, the same context must be used for all phases of a request, as it contains a reference to the interpreter.  To accomodate this, each context is bound (and locked) to a particular pool when the context is created, and is unbound (and unlocked) when the pool is destroyed.  When a context is needed, code should call {{{init_ctx(server_rec *s, apr_pool_t *p)}}}.  If {{{p}}} is non-null, {{{init_ctx}}} will either return the context bound to that Apache pool, or bind and return an available context if none is already bound.  If {{{p}}} is null, {{{init_ctx}}} will not bind the returned context to a pool, and will assume you will manage its lifecycle on your own.  This is useful in phases were a pool might outlive the scope of the context, because the context may never be unlocked.  This would quickly exhaust the context pool.  An example of this is the child_init phase, whose primary pool lasts for the lifetime of the child process, well beyond the scope of a child_init handler. 
     138 
     139When a context is in use, it is locked behind the scenes by {{{reserve_ctx}}} and unlocked by {{{release_ctx}}}.  We usually don't call these functions directly, relying on {{{init_ctx}}} and pool cleanup functions to do it for us.  However, if you passed a null pool to {{{init_ctx}}}, you MUST call {{{release_ctx}}} after the phase is complete to unlock the context for the next phase. 
    143140 
    144141== Apache Interface ==