|Version 12 (modified by jhorwitz, 5 years ago)|
NOTE: This is a work in progress.
This page describes the various subsystems of mod_parrot, and how they all work together. It will track mod_parrot trunk, so it may not accurately describe the latest release.
- HLL: high level language (e.g. Rakudo Perl 6, PHP)
- NCI: Parrot's native call interface, used to call C functions from Parrot
- HLL layer: code that implements a particular HLL Apache module
- Metahandler: code that implements a single Apache phase for a particular HLL
- PMC: Parrot Magic Cookie
- Context: a data structure containing information about the current connection
- Interpreter: a Parrot interpreter (Parrot_Interp)
- Provide a Parrot interface to the Apache API and data structures
- HLL modules require no C code
- Remain invisible to the end user
- Become the primary platform for mod_perl6 development
The mod_parrot Apache module is the product of compilation, and is usually named mod_parrot.so on Unix systems. It has a dependency on libparrot.so.
After installation, the module should be loaded as follows in the Apache configuration:
LoadModule parrot_module modules/mod_parrot.so
The module alone provides no HLL layers, and thus no real functionality by itself.
A context is a data structure that maintains state for mod_parrot during the various phases of a request. It is defined as modparrot_context in mod_parrot.h and contains the following members:
- Parrot_Interp interp - a Parrot interpreter bound to this context
- Parrot_Interp parent_interp - the parent interpreter (if any) of interp
- long count - UNUSED
- int locked - is this context in use? 0=available, 1=in use
- Various Apache data structures relevant to this request:
- request_rec *r
- apr_pool_t *pconf
- apr_pool_t *plog
- apr_pool_t *ptemp
- apr_pool_t *pchild
- server_rec *s
- conn_rec *c
- void *csd
- int module_index - identifies the current HLL module (index into the server configuration's module_array)
- int pool_index - index into the context pool array
The 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.
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).
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.
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.
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.
When the request/connection is complete, it is unlocked and disassociated from the connection by modparrot_conn_cleanup, a connection-scope pool cleanup handler.