Changes between Version 4 and Version 5 of ModParrotHLLDocs

Show
Ignore:
Timestamp:
12/25/08 18:57:23 (6 years ago)
Author:
jhorwitz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ModParrotHLLDocs

    v4 v5  
    5757=== Creating HLL Configurations === 
    5858 
    59 Each Apache module is responsible for defining and creating its own configuration data structures.  When Apache asks an HLL module for a server or directory configuration, mod_parrot will look for a subroutine in the {{{ModParrot;HLL;hllname}}} namespace to execute.  Server configs are provided by {{{server_create}}}, while directory configs are provided by {{{dir_create}}}.  These subroutines should create a data structure, possibly populated with default values, and return it.  The type of the structure is up to the implementor, as long as it is a valid Parrot PMC. 
     59Each Apache module is responsible for defining and creating its own configuration data structures.  When Apache asks an HLL module for a server or directory configuration, mod_parrot will look for a "constructor" subroutine in the {{{ModParrot;HLL;hllname}}} namespace to execute.  Server configs are provided by {{{server_create}}}, while directory configs are provided by {{{dir_create}}}.  These subroutines should create a data structure, possibly populated with default values, and return it.  The type of the structure is up to the implementor, as long as it is a valid Parrot PMC. 
    6060 
    61 ''Example: the PIR configuration subroutines'' 
     61''Signatures'' 
     62 
     63 * {{{PMC server_create()}}} 
     64 * {{{PMC dir_create()}}} 
     65 
     66''Example: the PIR configuration constructors'' 
    6267 
    6368{{{ 
     
    7681 
    7782=== Merging HLL Configurations === 
     83 
     84Like the constructor subroutines above, HLL modules can provide subroutines to merge two configurations.  This is useful when, for example, a particular configuration setting for a directory should be overridden by a different setting in a subdirectory.  Or perhaps your HLL is maintaining an array of values for a virtual host that should be concatenated with the array defined in the main server.  All of this behavior is performed by the merge subroutines. 
     85 
     86The server merge subroutine is called {{{server_merge}}}, and the directory merge is handled by {{{dir_merge}}}.  They are passed the "base" configuration and the "new" configuration, and are expected to return a merged configuration.  These subroutines should create a new PMC for the merged configuration rather than reusing the PMC from the "new" configuration.  Parrot passes PMCs by reference, and the code would thus be changing the "new" configuration directly, resulting in unexpected behavior. 
     87 
     88''Signatures'' 
     89 
     90 * {{{PMC server_merge(PMC basecfg, PMC newcfg)}}} 
     91 * {{{PMC dir_merge(PMC basecfg, PMC newcfg)}}} 
     92 
     93''Example: A self-hosted server merge from mod_perl6'' 
     94 
     95{{{ 
     96sub server_merge(%base, %new) 
     97{ 
     98    my %merged; 
     99 
     100    # merge handlers -- never inherit 
     101    for @server_phases.map({$_ ~ '_handler'}) -> $h { 
     102        %merged{$h} = %new{$h}; 
     103    } 
     104 
     105    return %merged; 
     106} 
     107}}} 
    78108 
    79109=== Custom Apache Directives ===