Section Intro: Dynamic Modules

THE META-HTML LANGUAGE REFERENCE MANUAL

Powerstrip System Tags

[TOC]

Elsewhen Module

Section Intro: Dynamic Modules

Dynamic Modules

Synopsis:

You can write C, C++, or other language code to implement your own built-in Meta-HTML functions. Such functions are first-class objects, and can manipulate the Meta-HTML environment directly, reset the parser pointer, manage hardware devices or talk on proprietery networks, or anything else that you would like to do.

It works by supplying you with the necessary Meta-HTML header files and a Makefile for building modules on your system. Using the supplied Makefile provides you with a resultant dynamically loadable module, which can be loaded into an invocation of the Meta-HTML server, engine, debugger, or standalone processor with the load-module function.

Combined with the autoload function, one can extend the Meta-HTML language without limits, and without forcing all of the functionality to be present all the time.

See the modules directory of the distribution for more details.

Commands:

load-module
module-call-function

module-function

unload-module

Variables:

MHTML::LOADED-MODULES

MHTML::MODULE-CAPABLE

MHTML::MODULE-DIRECTORIES

<load-module MODULE-NAME &key [NOINITIALIZE] [INITFUNC] Simple

Loads a module dynamically at runtime, adding the function definitions found therein to the global package of Meta-HTML functions.

load-module returns a non-empty string if the module is loaded successfully, or places an error in system-error-output if not. The string returned is the fully qualified pathname of the module just loaded.

MODULE-NAME is searched for by looking in each directory specified in the array mhtml::module-directories, or by loading the module as if the name specified is the full pathname to that file.

Once a module is loaded, the functions within it can be invoked just as with any standard Meta-HTML command.

See the examples.c file in the modules directory of your distribution for more information on writing Meta-HTML modules.

The keyword argument NOINITIALIZE when set to "true" says not to call the default initialization function of the module (module_initialize). This function is typically used to install the function names of the Meta-HTML callable functions present within the module. When such initialization is not required (perhaps you are planning to do this from within a different module), the use of this argument prevents the attempted call.

The keyword argument INITFUNC may be set to the name of the initialization function to call immediately after the module is loaded. If it is not set, or it is empty, the function module_initialize is called.

Example:

<set-var loaded? = <load-module /www/lib/example.so>>

<module-call-function MODULE-NAME FUNCTION-NAME &rest args> Simple

Call the function FUNCTION-NAME in the dynamically loaded module MODULE_NAME with character arguments of ARGS. It returns "true" if the function invocation took place. More likely, you will be crashing Meta-HTML without a way to debug it.

Up to ten arguments can be passed to the function.

It is so unlikely that you need this, that you will have to write me E-mail or read the source to see exactly how this works. If you are calling this function, the called function should not produce any output at all, and, in fact, there isn't a way for you to get output back from the function, since you can't pass the address of a variable, etc. This might be used to re-initialize some internals of your module, but you should really just provide an interface for that instead.

<module-function MODULE-NAME FUNCTION-NAME Simple

Returns the address of FUNCTION-NAME in MODULE-NAME if MODULE-NAME is an already loaded dynamic module, and FUNCTION-NAME is a function defined within that module.

Otherwise, it returns the empty string.

<load-module example>                 ==> /www/lib/example.so
<module-function example pf_apropos>  ==> 0X0EF8C437C

<unload-module MODULE-NAME Simple

Unloads a previously loaded dynamic module. You might want this if you are running Meta-HTML as a FastCGI, and the module was temporarily needed for some service, and was inordinately large.

Returns "true" if the module was successfully unloaded.

Edit Section
Function Index
Variable Index