Completing the documentation is one of the tasks we're trying to
finish up before releasing 4.5. Below is the complete man page for
ns_ictl as it currently stands. We'll be releasing a lot more
information about AOLserver 4.5 over then next few weeks as we
finish things up and begin testing internally here at AOL. Stay
tuned! :-)
- n
ns_ictl
NAME <http://gin.office.aol.com:8000/html/ns_ictl.n.htm#NAME>
SYNOPSIS <http://gin.office.aol.com:8000/html/ns_ictl.n.htm#SYNOPSIS>
DESCRIPTION <http://gin.office.aol.com:8000/html/
ns_ictl.n.htm#DESCRIPTION>
INTERPRETER ALLOCATION <http://gin.office.aol.com:8000/html/
ns_ictl.n.htm#INTERPRETER%20ALLOCATION>
INTERPRETER TRACES <http://gin.office.aol.com:8000/html/
ns_ictl.n.htm#INTERPRETER%20TRACES>
VIRTUAL SERVER TCL INITIALIZATION <http://gin.office.aol.com:8000/
html/ns_ictl.n.htm#VIRTUAL%20SERVER%20TCL%20INITIALIZATION>
EXAMPLES <http://gin.office.aol.com:8000/html/ns_ictl.n.htm#EXAMPLES>
SEE ALSO <http://gin.office.aol.com:8000/html/ns_ictl.n.htm#SEE%
20ALSO>
KEYWORDS <http://gin.office.aol.com:8000/html/ns_ictl.n.htm#KEYWORDS>
---------------------------------------------------------------------
---
_____________________________________________________________________
_________
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
[EMAIL PROTECTED] wrote:
How can you know exactly what variables to clean up in each
namespace? Even the cleanup for the global namespace doesn't
completely wipe out all variables.
This is exactly the problem we ran into when thinking about how
we could better support Tcl namespace variables in AOLserver
4.5. The short answer is that there doesn't necessarily seem to
be a good way to do this automatically for you, and instead it
will be up to each developer to delete the namespace variables
they have created:
ns_ictl trace deallocate {... your cleanup here ...}
In AOLserver 4.5 the callbacks have been cleaned up and now fire
in the right order, lifo for cleanups, fifo for inits. Hope that
helps!
I didn't know about this "trace" option for ns_ictl, it is not
documented:
http://www.panoptic.com/wiki/aolserver/Ns_ictl
is it equivalent to:
ns_ictl oncleanup script
Registers a script to be executed at Tcl interpreter cleanup time.
-john
--
AOLserver - http://www.aolserver.com/
To Remove yourself from this list, simply send an email to
<[EMAIL PROTECTED]> with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave
the Subject: field of your email blank.
--
AOLserver - http://www.aolserver.com/
To Remove yourself from this list, simply send an email to
<[EMAIL PROTECTED]> with the
body of "SIGNOFF AOLSERVER" in the email message. You can leave
the Subject: field of your email blank.