ns_ictl - Manipulate and introspect Tcl interpreter internals
These commands provides a mechanism to control Tcl interpreter initialization, cleanup, lifetime, synchronization etc.
Cleanup the interpreter. This function is used to close all currently open files, to destroy the global variables, destroy the (volatile) ns_sets, to abort all running requests and to call other cleanup callbacks. The function is called typically internally, e.g. at the end of a connection thread.
Cleanup and initialize the interpreter. This is used for long running detached threads to avoid resource leaks and/or missed state changes.
ns_thread begin {
while {1} {
ns_reinit
# ... long running work ...
}
}
Evaluate the given script and args and arrange for its side effects to propagate to all interpreters in all threads for the current virtual server. Use this to define new procs or to redefine existing procs once the server has started. A modified blueprint can be reloaded via ns_ictl update which is also called by the default init.tcl script of NaviServer during cleanup (i.e. by the deallocate traces).
If the script evaluates without error then it is appended to the interpreter initialization script. Other threads will begin to pick up the changes when they next run their delete traces and notice that the epoch has changed.
If the -sync option is given then ns_eval will return only after the interpreter initialization script has been updated. Otherwise, there might be a small delay before the initialization script receives the update due to ns_eval script's being evaluated in series.
If the -pending option is given a list of all scripts which are queued to be folded into the interpreter initialization script are returned.
Add a module to the list of modules to be initialized for the current virtual server and return the whole list. The modules are loaded later.
Invoke the legacy defer callbacks.
When during an update the maximum number of concurrent updates is reached, further updates are delayed until the count is again below this threshould. In such cases it is possible that some request will be still use the previous blueprint (similar to "eventually consistent" in distributed database systems).
Return the epoch (version) of the interpreter initialization script for the current virtual server. The epoch increases by 1 whenever ns_ictl save is called, such as by ns_eval.
Return the interpreter initialization script for the current virtual server.
Return the list of modules to be loaded for the current virtual server.
Return the script of the specified trace.
Mark the interpreter for deletion after the deallocate interpreter traces and have run. This is useful when it is necessary to delete an interp after it has been modified in a way that cannot be safely cleaned up, such as by the TclPro debugger.
Query or set the maximum number of automatic concurrent updates when the epoch changes. By default, this value is set to 1000 (practically unlimited).
This experimental option allows a server admin to configure, how many concurrent interpreter updates induced via epoch changes (e.g. on ns_eval) are allowed. This option is just useful for large sites with high number of connection threads defined. The default value for this parameter is sufficiently high, such that all updates will be performed by default potentially concurrent.
Background: For example, when a sites allows unlimited parallel updates, and the site has defined e.g. 100 connection threads, and every single update takes 1 second, then the request processing of the whole server comes to a complete standstill on epoch increments for at least for 1 second, since all threads will be busy with updates. When the number is sufficintly high it all available cores will be used, which will slow down the concurrent interpreter updates further. When the server will receive a higher number of requests (e.g. 800 per second), queueing will be inevitable (unless the number of concurrent updates is adjusted).
Run the scripts of the specified trace.
Replace the interpreter initialization script for the current virtual server. The newly saved script will be used to initialize newly created interpreters. Existing interpreters will be reinitialized when ns_ictl update is called.
Register an interpreter trace script.
create, allocate, getconn, and idle traces are called in FIFO (first in, first out) order; freeconn, deallocate and delete traces are called in LIFO (last in, first out) order.
All traces must be registered before server start up completes. Valid tracewhen options are:
Re-run the interpreter initialization script if it has changed since this interpreter was last initialized.
The following global configuration parameters can influence the default behavior of ns_ictl
ns_section ns/server {
# Activate/Deactivate concurrent interpreter create commands
#ns_param concurrentinterpcreate false ;# default: true
# Define maximum number of concurrent automatic update commands
# when epoch in increased (e.g. on "ns_eval" commands)
ns_param maxconcurrentupdates 5 ;# default: 1000
}