NaviServer - programmable web server
4.99  5.0

[ Main Table Of Contents | Table Of Contents | Keyword Index ]

ns_ictl(n) 4.99.30 naviserver "NaviServer Built-in Commands"

Name

ns_ictl - Manipulate and introspect Tcl interpreter internals

Table Of Contents

Synopsis

Description

These commands provides a mechanism to control Tcl interpreter initialization, cleanup, lifetime, synchronization etc.

COMMANDS

ns_cleanup

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.

ns_reinit

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 ...
   }
 }
ns_eval ?-sync? ?-pending? script ?args?

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.

ns_ictl addmodule modulename

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.

ns_ictl cleanup modulename

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).

ns_ictl epoch

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.

ns_ictl get

Return the interpreter initialization script for the current virtual server.

ns_ictl getmodules

Return the list of modules to be loaded for the current virtual server.

ns_ictl gettrace

Return the script of the specified trace.

ns_ictl markfordelete

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.

ns_ictl maxconcurrentupdates ?max?

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).

ns_ictl runtraces tracewhen

Run the scripts of the specified trace.

ns_ictl save script

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.

ns_ictl trace tracewhen script ?args?

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:

allocate

Allocate interpreter traces fire when an interpreter is first allocated for a particular thread, for example at the beginning of connection processing, job queue processing, or for a scheduled procedure.

create

Create traces fires when a new interpreter is first created. They are the first to be called, and are always called for every interpreter.

deallocate

Deallocate interpreter traces fire at the end of a transaction, after any getconn traces if running in a connection thread. A deallocate trace is a good place for general resource cleanup.

delete

Delete interpreter traces fire when an interpreter is deleted. Interpreters are often cached per-thread and reused multiple times, so a ?delete? trace may only fire when a thread exits or when ns_ictl markfordelete is called explicitly. They are the last trace to be called for an interp, and are always called, eventually.

freeconn

Freeconn interpreter traces fire after connection processing is complete, before any deallocate interpreter traces.

getconn

Getconn interpreter traces fire after all allocate traces have run, before connection processing for a URL begins.

Note: a getconn interpreter trace fires only once per connection, so if a Tcl proc is registered as a connection filter, that will trigger the getconn interpreter trace, otherwise it will fire later in the process when the registered proc, ADP, or Tcl page runs.

idle

Idle traces fire, when a connection thread is idle (received no requests within the thread's timeout and when minthreads is already reached, such that the timeouted thread is kept around. The timeout can be configured by the parameter threadtimeout in the ns/server/$servername section of the configuration file. This callback can be used e.g. for maintenance work on connection threads.

ns_ictl update

Re-run the interpreter initialization script if it has changed since this interpreter was last initialized.

EXAMPLES

 % ns_ictl epoch
 1
 % ns_ictl getmodules
 nsdb nslog nscp

Configuration

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
 }

See Also

ns_atclose

Keywords

callback, configuration, interpreter, module, ns_cleanup, ns_eval, ns_reinit, server built-in, trace