Version 3 (modified by jhorwitz, 6 years ago)

--

NOTE: This is a work in progress.

Overview

This page describes the various subsystems of mod_parrot, and how they all work together. It is meant to reflect the current state of mod_parrot and should not be used for future design notes. As such, it will be kept up to date with mod_parrot trunk.

Terminology

  • 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

Design Goals

  • 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

mod_parrot Module

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.

The module alone provides no HLL layers, and thus no real functionality by itself.

After installation, the module should be loaded as follows in the Apache configuration:

LoadModule parrot_module modules/mod_parrot.so

Configuration

Contexts

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)

The Apache data structures are all possible structures that may be passed to a handler. As a rule, if any of the Apache data structures are in scope, they MUST be populated in the context. This ensures that HLL metahandlers can access the proper data structures, as only they are only passed the context.

To maintain state, the same context must be used for all phases of a request, as it contains a reference to the interpreter.

Interpreter Management

Contexts are allocated from context pools, which contain a finite number of contexts created at startup. Contexts contain pointers to Parrot interpreters so this also provides mod_parrot with a pool of interpreters.

Interpreter Lifecycle

Interpreters are created

Apache Interface

NCI Functions

Parrot Objects

HLL Modules

Module Registration

Metahandlers

Multiprocessing Module Support

Prefork MPM

Threaded MPM (e.g. worker)