NaviServer - programmable web server

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

# ns_ictl(n) 4.99.8 naviserver "NaviServer Built-in Commands"

## Name

ns_ictl - Manipulate and introspect Tcl interpreter internals

## Table Of Contents

## Synopsis

- ns_cleanup
- ns_reinit
- ns_eval ?-sync? ?-pending? script ?args?
- ns_ictl trace tracewhen script ?args?
- ns_ictl markfordelete
- ns_ictl addmodule modulename
- ns_ictl getmodules
- ns_ictl get
- ns_ictl epoch
- ns_ictl save script
- ns_ictl update

## Description

These commands provides a mechanism to control Tcl interpreter initialisation, 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 http requests and to call other cleanup callbacks. The function is called typically internally, eg. at the end of a connection thread.

ns_reinit

  Cleanup and initialise 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 it's side effects to propagate to all interpreters in all threads for the current virtual server. Use this to define new procs once the server has started.

  If the script evaluates without error then it is appended to the interpreter intialisation 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 initialisation script has been updated. Otherwise, there might be a small delay before the initialisation 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 inerpreter initialisation script are returned.

ns_ictl trace tracewhen script ?args?

  Register an interpreter trace script.

  create, allocate and getconn 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:

  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.

  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.

  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.

  freeconn

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

  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.

ns_ictl markfordelete

  Mark the interpreter for deletion after the deallocate interpreter traces and have run. This is useful when it's 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 addmodule modulename

  Add a module to the list of modules to be initialised for the current virtual server and return the whole list. The modules are loaded later.

ns_ictl getmodules

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

ns_ictl get

  Return the interpreter initialisation script for the current virtual server.

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 save script

  Replace the interpreter initialization script for the current virtual server. The newly saved script will be used to initialise newly created interpreters. Existing interpreters will be be reinitialised when ns_ictl update is called.

ns_ictl update

  Re-run the interpreter initialisation script if it has changed since this interpreter was last initialised.

## EXAMPLES

    % ns_ictl epoch
    1

    % ns_ictl getmodules
    nsdb nslog nscp

## See Also

ns_atclose

## Keywords

callback, interpreter, module, ns_cleanup, ns_eval, ns_reinit, trace