webmcp

diff doc/autodoc-header.htmlpart @ 507:ac5f7a40b8c4

Extended documentation (mostly on "Configuration, pre-fork and post-fork initializers")
author jbe
date Sun Aug 20 23:12:16 2017 +0200 (2017-08-20)
parents 0221836a9db5
children 6c819040ef6f
line diff
     1.1 --- a/doc/autodoc-header.htmlpart	Wed Aug 16 00:31:11 2017 +0200
     1.2 +++ b/doc/autodoc-header.htmlpart	Sun Aug 20 23:12:16 2017 +0200
     1.3 @@ -43,7 +43,7 @@
     1.4          margin-bottom: 0.3ex;
     1.5        }
     1.6        p {
     1.7 -        margin: 0px;
     1.8 +        margin-bottom: 1ex;
     1.9          line-height: 130%;
    1.10        }
    1.11        tt, pre {
    1.12 @@ -63,7 +63,7 @@
    1.13        .autodoc_entry .short_synopsis {
    1.14          cursor: pointer;
    1.15        }
    1.16 -      .autodoc_details {
    1.17 +      .AUTODOC_details {
    1.18          padding-left: 1em;
    1.19          padding-right: 1em;
    1.20          border: 1px solid #777;
    1.21 @@ -95,11 +95,39 @@
    1.22      </p>
    1.23      <h2>Installation</h2>
    1.24      <p>
    1.25 -      After downloading the tar.gz package, unpack it, enter the unpacked directory and type <tt>make</tt>. If you use Mac OS X or if you experience problems during compilation, you need to edit the <tt>Makefile.options</tt> file prior to compilation. The framework itself will be available in the <tt>framework/</tt> directory, while a demo application is available in the <tt>demo-app/</tt> directory. The <tt>framework.precompiled/</tt> and <tt>demo-app.precompiled/</tt> directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with <tt>cp -L</tt> to follow links) to any other place you like. Don't forget to setup a database, and make the <tt>tmp/</tt> directory of the application writable for the web server process. Good luck and have fun!
    1.26 +      After downloading the tar.gz package, unpack it, enter the unpacked directory and type <tt>make</tt>. If you use Mac OS X or if you experience problems during compilation, you need to edit the <tt>Makefile.options</tt> file prior to compilation. The framework itself will be available in the <tt>framework/</tt> directory, while a demo application is available in the <tt>demo-app/</tt> directory. The <tt>framework.precompiled/</tt> and <tt>demo-app.precompiled/</tt> directories will contain a version with all Lua files being byte-code pre-compiled, which can be used instead. You may copy these directories (with <tt>cp -L</tt> to follow links) to any other place you like. Don't forget to setup a database, and make the <tt>tmp/</tt> directory of the application writable for user who executes WebMCP. Good luck and have fun!
    1.27 +    </p>
    1.28 +    <h2>Configuration, initializers, and request handling</h2>
    1.29 +    <p>
    1.30 +      WebMCP uses the <a href="http://www.public-software-group.org/moonbridge">Moonbridge Network Server</a> to handle HTTP requests. The Moonbridge Network Server listens to a TCP port and passes control to WebMCP by calling <a href="#request.handler"><tt>request.handler(...)</tt></a> for each request. However, before each request is processed, WebMCP will initialize the environment. This initialization includes tasks such as
    1.31 +    </p>
    1.32 +    <ul>
    1.33 +      <li>loading libraries,</li>
    1.34 +      <li>configuring the database connection or the application,</li>
    1.35 +      <li>connecting to the database,</li>
    1.36 +      <li>etc.</li>
    1.37 +    </ul>
    1.38 +    <p>
    1.39 +      For each request, it is also possible to execute filters. Filters can be used to
    1.40      </p>
    1.41 -    <h2>Configuration, pre-fork and post-fork initializers</h2>
    1.42 +    <ul>
    1.43 +      <li>
    1.44 +        restrict access for certain requests, e.g. by performing redirects or raising errors
    1.45 +      </li>
    1.46 +      <li>
    1.47 +        perform tasks that are common for different requests, e.g.
    1.48 +        <ul>
    1.49 +          <li>execution certain database requests,</li>
    1.50 +          <li>prepare a menu on the website,</li>
    1.51 +          <li>&hellip;</li>
    1.52 +        </ul>
    1.53 +      </li>
    1.54 +    </ul>
    1.55      <p>
    1.56 -      The Moonbridge Network Server creates forks (i.e. clones) of the application server process in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. The application's configuration files as well as its pre-fork initializers are executed before forking. The application's post-fork initializers are executed after forking. In particular, any libraries that open file or network handles during initialization must not be loaded before the server process is forked. Opening database connections must be performed after forking as well. Execution order is as follows:
    1.57 +      Filters and initializers are created by adding files in the application's directory structure. The filename determins the execution order of otherwise equally ranked initializers and/or filters. It is a common idiom to start the filename of a filter or initializer with a two digit number to be easily able to change the execution order when desired. Filters and initializers are executed both before and after a request. Each file must contain a command <a href="#execute.inner"><tt>execute.inner()</tt></a>. The part before that command is executed before the request, and the part after that command is executed after the request.
    1.58 +    </p>
    1.59 +    <p>
    1.60 +      The Moonbridge server creates forks (i.e. clones) of the application server process (i.e. the whole Lua engine including all libraries and variables) in order to handle concurrent requests. Certain initializations may be performed before forking, other initializations must be performed after forking. For this purpose, WebMCP allows an application to provide so-called "pre-fork" and "post-fork" initializers. The application's configuration files as well as its pre-fork initializers are executed before forking. The application's post-fork initializers are executed after forking. In particular, any libraries that open file or network handles during initialization must not be loaded before the server process is forked. Opening database connections must be performed after forking as well. WebMCP follows the following execution order (directory structure is explained further down):
    1.61      </p>
    1.62      <ol>
    1.63        <li>
    1.64 @@ -151,7 +179,7 @@
    1.65    { proto = "tcp", host = "::", port = 8080 },
    1.66    { proto = "tcp", host = "0.0.0.0", port = 8080 }
    1.67  }
    1.68 -execute.inner()  -- if done in pre-fork initializer</pre>
    1.69 +execute.inner()  -- only use this line if done in pre-fork initializer</pre>
    1.70      <h2>Using the atom library</h2>
    1.71      <p>
    1.72        Lua itself has only very few built-in data types. The atom library gives support for extra data types. Currently the following extra data types are provided:

Impressum / About Us