Changes between Version 21 and Version 22 of ModParrotHLLDocs

Timestamp:

12/25/08 22:17:48 (5 years ago)

Author:

jhorwitz

Comment:

--

ModParrotHLLDocs

@@ -224 +224 @@
 == Metahandlers ==
 
-Metahandlers are responsible for implementing the semantics of an HLL module for each Apache phase.  If a module registers a hook with Apache, mod_parrot will call the metahandler for that hook during that phase.  The metahandler then executes the actual HLL handler code specified in the configuration and returns the status.  In this way, the metahandler acts as a proxy, hiding the implementation details of the HLL module from Apache and mod_parrot.  For example, mod_perl6 passes an Apache::RequestRec object to response handlers, but mod_parrot doesn't know that -- it's up to the mod_perl6 metahandler to pass the Apache::RequestRec object to the handler code.
+Metahandlers are responsible for implementing the semantics of an HLL module for each Apache phase.  If a module registers a hook with Apache, mod_parrot will call the metahandler for that hook during that phase.  The metahandler then executes the actual HLL handler code specified in the configuration and returns the status.  In this way, the metahandler acts as a proxy, hiding the implementation details of the HLL module from Apache and mod_parrot.  For example, mod_perl6 passes an {{{Apache::RequestRec}}} object to response handlers, but mod_parrot doesn't know that -- it's up to the mod_perl6 metahandler to pass the {{{Apache::RequestRec}}} object to the handler code.
 
 === Apache Hooks ===
@@ -352 +352 @@
 == Registering the HLL Apache Module ==
 
+Now that we have all of this information, we can finally register our HLL module.  The only missing piece is the name of the module.  The mod_parrot convention is {{{modparrot_hllname_module}}}, where {{{hllname}}} is the name of your language (e.g. {{{modparrot_perl6_module}}}).  This will prevent name clashes with non-mod_parrot modules for the same language, which is likely for languages like PHP and Python that already have modules.
+
+With the name in hand, we can call {{{ModParrot;Apache;add_module}}} to register our module.  Its prototype is as follows:
+
+{{{VOID add_module(STRING module_name, STRING hll_namespace, PMC command_array, PMC hook_array)}}}
+
+{{{hll_namespace}}} is the namespace of your module under {{{ModParrot;HLL}}}.
+
+There is no return value from this subroutine; errors that occur when registering a module are fatal and will print an error message and exit.
+
+''Example: Registering the PIR HLL module''
+
+{{{
+    add_module = get_hll_global [ 'ModParrot'; 'Apache'; 'Module' ], 'add'
+    add_module("modparrot_pir_module", "PIR", cmds, hooks)
+}}}
+
+HINT: If you are registering ALL hooks, use an array with the single value MP_HOOK_ALL, rather than populating the array with every hook constant.
+
 == Miscellany ==