Provided by: aolserver4-dev_4.5.1-16_amd64 
NAME
ns_ictl - Facility to control AOLserver multi-threaded Tcl interpreters
SYNOPSIS
ns_ictl addmodule module
ns_ictl cancel thread
ns_ictl cleanup
ns_ictl epoch
ns_ictl get
ns_ictl getmodules
ns_ictl gettraces which
ns_ictl once key script
ns_ictl oncleanup script
ns_ictl oncreate script
ns_ictl ondelete script
ns_ictl oninit script
ns_ictl package ?-exact? package ?version?
ns_ictl runtraces which
ns_ictl save script
ns_ictl threads
ns_ictl trace when script
ns_ictl update
_________________________________________________________________
DESCRIPTION
This command provides access to the internal facilities to control and configure multi-
threaded Tcl interpreters in the context of AOLserver virtual servers. It is normally
used in startup initialization scripts to define how new interpreters are initialized when
created and to support cleanup and re-initalization between transactions (e.g., HTTP
connections).
ns_ictl addmodule module
Add a module to the list of modules to be initialized at startup. This command is
not normally required as each module specified in the AOLserver modules config
section for the corresponding server (e.g., ns/server/server1/modules) is
automatically added to the list.
ns_ictl cancel thread
Send an asynchronous interrupt request to the specified thread, cancelling any
script currently executing on any AOLserver created interpreter (note the interrupt
is not virtual-server specific). This command utilizes the facilities of
Tcl_AsyncMark to mark as ready a callback registered with Tcl_AsyncCreate. The
callback places an error message in the interpreter result and returns TCL_ERROR to
unwind the call stack. The underlying Tcl facility has limitations, e.g., the
interrupt will only be noticed when Tcl checks via Tcl_AsyncReady calls between
commands and the interrupt can be caught with a catch command. See the man page
for Tcl_AsyncCreate for details.
ns_ictl cleanup
This command invokes any callbacks registered during a transaction via the C-level
Ns_TclRegisterDefer routine. Unlike callbacks registered with the ns_ictl trace
deallocate command or Ns_TclRegisterTrace routine, these callbacks are executed
only once and there is no Tcl-level access to the underlying Ns_TclRegisterDefer
routine.
ns_ictl epoch
This command returns the unique id for the current duplication script for the
virtual server. The id starts as 0 when the virtual server is created and is
incremented each time a new script is saved via the ns_ictl save command.
ns_ictl get
Return the current duplication script for the virtual server. This command is
useful to view the duplication script created by the initialization script at
startup.
ns_ictl getmodules
Return the list of modules to be initialized at startup. This list corresponds to
the names of modules specified in the virtual server modules config section, e.g.,
ns/server/server1/modules unless additional modules are added via the ns_ictl
addmodule command.
ns_ictl gettraces which
Return the list of traces which will be invoked at the specified time. The which
argument can be one of create, delete, allocate, deallocate, getconn, or freeconn.
The traces are returned in the order in which they will be executed. Script level
traces are returns as strings to evaluate and C-level traces are returned with
strings which specify the address of the underlying C procedure and argument.
ns_ictl once key script
Evaluate given script once in the virtual server. The given key is a string name
which uniquely identifies the corresponding script. This command is useful in a
Tcl package which includes one-time initialization routines, e.g., calls to
ns_register_proc or initialization of shared variables using nsv_set (see EXAMPLES
below).
ns_ictl oncleanup script
This command is equivalent to ns_ictl trace deallocate script.
ns_ictl oncreate script
This command is equivalent to ns_ictl trace create script.
ns_ictl ondelete script
This command is equivalent to ns_ictl trace delete script.
ns_ictl oninit script
This command is equivalent to ns_ictl trace allocate script.
ns_ictl package ?-exact? package ?version?
This command is used to require a package in the calling interpreter and, if
successfully loaded, in all other interpreters for the virtual server. In addition
to ensuring version consistency for the package, it is equivalent to:
set version [package require package ?version?]
ns_ictl trace allocate [list package require package $version]
ns_ictl runtraces which
This command runs the requested traces. The which argument must be one of create,
delete, allocate, deallocate, getconn, or freeconn. Direct calls to this command
are not normally necessary as the underlying C code will invoke the callbacks at
the required times. Exceptions include calling ns_ictl runtraces or testing
purposes or to mimic the normal cleanup and initialization work performed on
between transactions in a long running thread (see EXAMPLES below).
ns_ictl save script
Save the given script as the duplication script, incrementing the virtual server
epoch number. This command is normally called by the bootstrap script after
constructing the script to duplicate the procedures defined by sourcing the various
module initialization script files.
ns_ictl threads
Return a list of all threads with interpreters for the virtual server. The ids
return are small strings which represent the underlying thread ids and can be
passed to the ns_ictl cancel command to send an asynchronous cancel request.
ns_ictl trace create script
Register script to be called when an interpreter is first created. This is useful
to create procedures, require packages, or initialize other state to be used during
the lifetime of the interpreter.
ns_ictl trace delete script
Register script to be called before an interpreter is destroyed. This is useful to
free any resources which may have been allocated for the interpreter during the
lifetime of the interpreter.
ns_ictl trace allocate script
Register script to be called each time an interpreter is allocated for use by the
Ns_TclAllocateInterp routine. This is useful for reinitializing resources which may
be used during a single transaction in the interpreter.
ns_ictl trace deallocate script
Register script to be called each time an interpreter is returned after a
transaction with the Ns_TclDeAllocateInterp routine. This is useful for garbage
collection, i.e., freeing any resources which may be used during a single
transaction in the interpreter.
ns_ictl trace getconn script
Register script to be called each time an interpreter is returned and associated
with an HTTP connection with the Ns_GetConnInterp routine. This could be useful to
define variables relative to the HTTP request.
ns_ictl trace freeconn script
Register script to be called each time an HTTP connection is closed. This could be
used to log information about the request, e.g., timing statistics. Note that the
interpreter may still be actively evaluating a script after the connection is
closed, i.e., this is not equivalent to ns_ictl trace deallocate for connection-
related interpreters.
ns_ictl update
This command can be used to atomically compare the epoch of the current duplication
script with the epoch of the interpreter, evaluating the script and updating the
epoch in the interpreter if they do not match. This command is generally
registered as a callback with ns_ictl trace allocate by the legacy initialization
code.
INTERPRETER ALLOCATION
Tcl interpreter in AOLserver are available on demand with state specific to a virtual
server. These interpreters are also expected to be reused for multiple transactions
(e.g., HTTP connections, scheduled procedures, socket callbacks).
To support reuse, AOLserver provides the C-level Ns_TclAllocateInterp routine to allocate
an interpreter from a per-thread cache (creating and initializing a new interpreter if
necessary) and the Ns_TclDeAllocateInterp routine to return an interpreter to the cache
when no longer required. All interpreters in the per-thread cache are destroyed when a
thread exists.
In general, only C-level extension writers need to call the C-level API's directly; the
various Tcl-level interfaces in AOLserver (e.g., ADP pages, ns_regiseter_proc,
ns_schedule_proc, ns_thread, etc.) allocate and reuse interpreters using the C-level API's
automatically before invoking the cooresponding script or ADP page.
INTERPRETER TRACES
To ensure a consistent state of interpreters when allocated and enable cleanup and
reinitialization between transactions, each virtual server maintains a list of callbacks
to be invoked at various points in the lifetime of an interpreter. These callbacks are
generally installed when the server is initialized at startup and then called
automatically by the Ns_TclAllocateInterp and Ns_TclDeAllocateInterp API's at the
appropriate times and in consistent order. The Ns_TclRegisterTrace routine can be used to
register C-level callbacks and the ns_ictl trace command can be used to register Tcl
script callbacks. The ns_ictl gettraces command can be used to list all currently
registered callbacks, both at the Tcl script and C level.
Callbacks registered via the tracing facility are invoked in a specific order depending on
the type. Initialization style callbacks including create, allocate, and getconn are
invoked in FIFO order, with all script callbacks invoked after all C-level callbacks.
This enables extension writers to utilize the facilities of previously initialized
extensions. Correspondingly, cleanup style callbacks including freeconn, deallocate, and
delete are invoked in LIFO order, with all scripts callbacks invoked before C-level
callbacks. This helps avoid the possibility that a cleanup callback utilizes features of a
previously cleaned up extension.
In addition, the ns_ictl package command can be used to consistently manage the loading of
a Tcl package in all interpreters for a virtual server. This feature is mostly a
convenience routine built above the generic trace framework with additional checks to
ensure version number consistency. Coupled with ns_ictl once, the ns_ictl package command
provides a clean framework to utilize Tcl packages in multi-threaded AOLserver (see
EXAMPLES).
VIRTUAL SERVER TCL INITIALIZATION
AOLserver also supports a Tcl initialization framework for virtual servers based on
callbacks registered by loadable modules and the sourcing of scripts files located in
corresponding directories. Options to ns_ictl to support this framework include save,
get, epoch, and update and are used in conjunction with the generic tracing facility by
the virtual server bootstrap script (normally bin/init.tcl). The ns_eval command also
relies on this framework to support dynamic update of the state of interpreters.
This initialization framework pre-dates the Tcl package facilities and utilizes
introspection of the state of a startup interpreter at the end of initialization to
construct a single script which attempts to duplicate the state in subsequent
interpreters. Steps taken during this initialization include:
1. Load all modules in the server's module config section, e.g.,
ns/server/server1/modules. Modules with Tcl C-level extensions typically call the
legacy Ns_TclInitInterps routine or the more general Ns_TclRegisterTrace routine
with the NS_TCL_TRACE_CREATE flag in their module init routine to register a
callback to invoke when new interpreters are created. The callback normally
creates one or more new commands in the interpreter with Tcl_CreateObjCommand but
may perform any per-interpreter initialization required, e.g., creating and saving
private state with the Tcl_SetAssocData facility. In addition, as modules are
loaded, the string name of the module is added to the list of known modules.
2. After all C modules are loaded, AOLserver creates a new Tcl
interpreter for the virtual server, executing any trace callbacks already
registered via the loaded C modules (e.g., any Ns_TclInitInterps callbacks) and
then sources the virtual server bootstrap script, normally bin/init.tcl. This
script creates a few utility procedures and then sources all private and public
script files in directories which correspond to loaded modules in the order in
which they were loaded. These directories are normally relative to the virtual
server and to the AOLserver installation directory, e.g., initialization script
files for the module mymod in the server1 virtual server would be searched for in
the servers/server1/modules/tcl/mymod/ and modules/tcl/mymod/. Any init.tcl file
found in each directory is sourced first with all remaining files sourced in
alphabetical order. In addition, any files in the public directory with identical
names to files in the private directory are skipped as a means to enable
overloading of specific functionality on a per-server basis. In practice, most
modules only contain shared utility procedures defined in the public directories
and the private directories are empty or non-existant. The script files normally
contain a mix of commands to evaluate once for server configuration (e.g., a call
to ns_register_proc to bind a Tcl procedure to an HTTP request URL) with proc and
namespace commands to provide additional functionality in the interpreter.
3. After all script files have been sourced, the bootstrap script
code then uses a collection of recursive procedures to extract the definitions of
all procedures defined in all namespaces. The definitions are used to construct a
script which attempts to duplicate the state of the initialization interpreters.
This scripts is then saved as the per-virtual server duplication script with the
ns_ictl save command which also increments the epoch to 1. There are limits to
this approach to determine the full state, e.g., it does not attempt to duplicate
any global variables which may have been defined in the startup scripts. Typically,
startup scripts will use nsv_set or other mechanisms to store such shared state.
4. The bootstrap code then uses the ns_ictl trace allocate
command to register a callback to the ns_ictl update command each time an
interpreter is allocated for use. In practice, interpreters are created with the
default epoch of 0 and the first call to ns_ictl update determines an out-of-date
condition, evaluates the duplication script, and increments the interpreter's epoch
to 1 to match the state created by the startup interp.
5. Subsequent calls the ns_eval, if any, will evaluate the
given script and then re-generate and save the duplication script as was done at
startup, incrementing the epoch once again. In this way, dynamic updates which are
detected in other interpreters on their next call to ns_ictl update can be
supported in a limited fashion.
In practice, while generally successful, this duplication technique has inhibited the
clean use of proper Tcl package extensions and encouraged the use of the ns_eval command
which is generally not recommended for the non-deterministic manner in which it attempts
to dynamically reconfigure a server. Also, commands required to configure the server once
(e.g., calls to ns_register_proc) are inter-mixed with proc commands designed to extend
functionality in all interpreters, complicating configuration management.
As an alternative, the example below illustrates a means to more explicitly manage
configuration through a combination of direct calls to ns_ictl trace create and ns_ictl
once. Unfortunately, the all encompassing nature of the legacy initialization approach
makes it difficult to incrementally move to this cleaner approach because the duplication
script construction code is unable to distinguish between state created with the newer,
cleaner ns_ictl commands and state created as a side effect of one or more script files
being sourced. As such, it is expected the legacy initialization framework will remain in
place until AOLserver 5.x when it will be removed entirely in a non-backwards compatible
move towards the cleaner API's.
EXAMPLES
This example illustrates the use of ns_ictl package and ns_ictl once to load an AOLserver-
aware Tcl package into a virtual server. The following code could be added to the virtual
server bootstrap script, bin/init.tcl, to load MyPkg in the virtual server:
#
# Startup code in bin/init.tcl:
#
# Load MyPkg in all interps (including this one).
#
ns_ictl package require MyPkg
This call will result in the package being loaded into the startup interpreter in the
ordinary Tcl fashion (see the package man page for details). Ordinary Tcl extension
packages would need no modifications but packages which utilize AOLserver-specific
features or require garbage collection between transactions could also use ns_ictl for
finer grained control. For example, the init.tcl script specified by the package ifneeded
command in the MyPkg package's pkgIndex.tcl file could contains:
#
# Package code in lib/myPkg1.0/init.tcl:
#
#
package provide MyPkg 1.0
#
# Server init which will be executed the first time called,
# normally in the context of the startup interpreter as above.
#
ns_ictl once MyPkg {
# Register the run Tcl proc HTTP handler.
ns_register_proc /mypkg mkpkg::run
# Register a garbage collection callback.
ns_ictl trace deallocate mypkg::cleanup
}
#
# Code which will be invoked to initialize the package in
# all interpreters when required.
#
proc mypkg::run {} {
... handle /mypkg requests ...
}
proc mkpkg::cleanup {} {
... cleanup transaction resources for mypkg, e.g., db handles ...
}
SEE ALSO
Ns_TclAllocateInterp(3), Ns_TclDeAllocateInterp(3), Ns_GetConnInterp(3),
Ns_FreeConnInterp(3), Ns_TclInitInterps(3), Ns_TclRegisterTrace(3),
Ns_TclRegisterDeferred(3), ns_atclose(n), ns_eval(n).
KEYWORDS
threads, interpreters, traces, initialization