Apache module specific commands

Note that these commands are implemented as dummies in the CGI version of Websh only. They don't do anything except for web::initializer and web::finalizer, which just evaluate the code provided in the argument.

web::initializer

web::initializer code

This code is executed only when a new interpreter is created. Note that the "main" Websh script can source several modules which each call their initialization code. Also note that this code eval'd when it is first requested and read in its normal script sequence, and not prior to any other code in the script.

Calling web::loglevel and web::logdest in any web::initializer will tag these log levels and destinations as not to be deleted, after the request ends. This log condifguration will therefore also be available in the finalizer code, which is only eval'd after the last request in the interpreter has been cleaned up.

Example 17. logging in web::initializer

> cat test.ws3
web::initializer {
    web::logdest add user.-debug file -unbuffered /tmp/test.log
    web::logfilter add *.-debug
    web::log info "initializing interp"
}

web::command default {
    web::log info "command default call number [web::interpcfg  numreq]"
    web::putxfile /tmp/dummypage.html
}

web::finalizer {
    web::log info "shutting down interp"
}

web::dispatch

> # requesting test.ws3 three times over mod_websh:
> more /tmp/test.log
10/28/05 14:13:45 [20639] user.info: initializing interp
10/28/05 14:13:45 [20639] user.info: command default call number 0
10/28/05 14:13:46 [20639] user.info: command default call number 1
10/28/05 14:13:47 [20639] user.info: command default call number 2
10/28/05 14:13:47 [20639] user.info: shutting down interp

Note that in the above example the lifetime of the interpreter class is set to 3 requests. (See command web::interpclasscfg.)

web::finalizer

web::finalizer code

Register code to be exectuted when the interpreter for this Websh script is deleted. web::finalize will then call each code block that has been registered, starting with the most recently added code.

web::finalize

web::finalize

Execute finalizer code that has been registerd using web::finalizer, starting with the most recently added code. Note that this command is executed automatically and does not have to be called manually. However, it can be used as a hook, when the interpreter is deleted:

Example 18. web::finalize hook

rename web::finalize web::finalize.orig
proc web::myFinalize {} {
    # code to eval before finalize.orig
    finalize.orig
    # code to eval after finalize.orig
}	  


web::maineval

web::maineval code

Execute code in the "main" interpreter of mod_websh. (Note that this is synchronized, i.e. the main interpreter is locked for exclusive access by the current thread within the process. However, running Apache in a prefork setting sets up a main interpreter per child, so the exclusive access does not refer to server wide exclusivity, but only to child process wide exclusiveity.)

web::interpclasscfg

web::interpclasscfg classid property ?value?

Properties are: maxrequests, maxttl, maxidletime Set or accesses properties of the interpreter class classid.

web::interpclasscfg classid maxrequests ?value?
gets or sets the maximum number of requests interpreters of this class should handle. If value is 0, handle an unlimited number of requests. Default: 1.
web::interpclasscfg classid maxttl ?value?
gets or sets the maximum number of seconds interpreters of this class should live. If value is 0, it lives forever. Default: 0.
web::interpclasscfg classid maxidletime ?value?
gets or sets the maximum number of seconds interpreters of this class should live beeing idle. If value is 0, no idle timeout is assumed. Default: 0.

web::interpcfg

web::interpcfg ?property? ?value?

Properties are: numreq, retire, starttime, lastusedtime Sets or accesses properties of the current interpreter.

web::interpcfg
returns classid of current interpreter.
web::interpcfg numreq
gets the number of requests handled by this interpreter.
web::interpcfg retire ?boolean?
gets or sets the flag indicating this interpreter should be removed after handling the current request.
web::interpcfg starttime
returns the time in seconds since the epoch, this interpreter was started.
web::interpcfg lastusedtime
returns the time in seconds since the epoch, this interpreter was last used (starttime in case of first request).

web::interpmap

web::interpmap filename

Hook to define interpreter classes depending on the requested file. Note that this hook must be defined in the Websh configuration file (WebshConfig directive of mod_websh).

When a request is directed to mod_websh, Websh needs to determine the interpreter class for that reqest. It does that by calling web::interpmap with the requested file as argument. The return value of that command is the name of the interpreter class and at the same time the filename of the script for this interpreter class.

Example 19. web::interpmap

proc web::interpmap {filename} {
    if {[string match "/path/to/myApp" $filename]} {
        # this is my special app
        return /real/path/to/myApp
    }
    if {[string match "*.ws3"]} {
        # scripts have their own interp class
        return $filename
    }
    # default: all templates are handled by my handler
    return /my/special/template/handler
}	  


The default implementation of web::interpmap is

proc web::interpmap {filename} {return $filename}

which sets up a separate interpreter class for every requested URL and takes the file itself as script.