ns_proxy - Execute Tcl scripts in an external process
ns_proxy provides a simple, robust proxy mechanism to evaluate Tcl scripts in a separate, pipe-connected process. This approach can be useful both to isolate potentially thread-unsafe code outside the address space of a multithreaded process such as NaviServer or to enable separation and timeout of potentially misbehaving, long running scripts.
The command is provided by the nsproxy dynamic library which can be loaded into an interpreter via the Tcl load command, for example:
load "/usr/local/lib/libnsproxy.so" ns_proxy ...
It is also possible to load the library into all interpreters of a NaviServer virtual server by specifying an nsproxy.so entry in the server's module config entry, for example:
ns_section "ns/server/server1/modules" {
ns_param nsproxy nsproxy.so
}
When loaded, the library adds the single ns_proxy command with takes multiple options as described below. Proxies (i.e. worker processes) are normally created on demand when requested and connected to the parent process via pipes used to send scripts and receive response. Proxies remain active until the parent process exits, effectively closing all pipes to the worker processes, or when their idle timer expires, depending on the setup of the pool (see ns_proxy configure).
Proxies are obtained from their corresponding pool by means of the ns_proxy get command. Only the thread that obtained the proxy can use it to communicate with the worker process. In order to allow other threads to use the same proxy, the thread must return (via the ns_proxy put or ns_proxy cleanup commands) the proxy back to its corresponding pool. One thread can obtain one or a bunch of proxies from a pool in one step. It cannot, however, repeatedly obtain proxy by proxy in a loop, as this may lead to difficult-to-trace deadlock situation (see ns_proxy get command).
All the timeout values below (no matter if these are used in positional or arguments, or as parameters in the configuration file) can be specified with time units. If the timeout value time has no time unit, seconds are assumed.
Returns a list of currently evaluating scripts in proxies for the given pool.
The output is one or more lists, depending on the optional ?handle? argument. If the optional argument is given, only the status of the proxy for the given handle is returned and the result is a one-element list. Otherwise, statuses of all active proxies for the given pool are returned and the result is a list of two or more elements.
Each element itself is a list which includes several keys: handle, worker, start, script and their associated values. This format is suitable for filling in a Tcl array with the array set Tcl command. The handle key contains the handle of the proxy. The worker key contains the process-id of the worker process. The start key contains the timestamp with the absolute time when this proxy has been activated. The timestamp is in format that ns_time command understands.
The script contains the script passed to the proxy for execution. It is also possible to view the currently evaluating scripts with the Unix ps command as the proxy worker process re-writes its command argument space with the request script before evaluation and clears it after sending the result.
Releases any handles from any pools currently owned by a thread.
This command is intended to be used as part of a garbage collection step. Calling this command within NaviServer is not necessary as the module registers a trace to release all handles via the ns_ictl trace deallocate facility when interpreters are deallocated after some transaction, for example, at the end of a connection.
Stop all worker processes attached to free proxies for the given pool. If the optional handle is given, it stops the process only for that handle.
Configures options for the pool. The pool is created with default options if it does not already exist. Default options for the pool are taken from the NaviServer configuration file under the section "ns/server/$server/module/nsproxy". In case the library is loaded in plain Tcl shell, default configuration options are fixed and cannot be changed w/o recompiling the code. Configurable options include:
Evaluates script in the proxy specified by handle. The optional ?timeout? argument specifies a maximum time to wait for the command to complete before raising an error (see ERROR HANDLING below for details on handling errors).
Alternatively, the handle itself may be used as Tcl command like in the example below:
set handle [ns_proxy get mypool] $handle "short_running_proc" $handle "long_running_proc" 20000
Returns a list of all free proxies for the given pool. Free proxies are those which are left in the pool queue waiting to be used by the ns_proxy get command. Some proxies may have an active worker process attached, some not. If a worker process is not attached to the free proxy, a new one will be created as soon as the proxy is requested by some thread.
Returns one or more handles to proxies from the specified pool. If no worker process has been started yet, or when additional worker processes are required, and it is permitted by the configuration, these worker processes will be started.
The pool will be created with default options if it does not already exist. The optional -handle can be used to specify the number of handles to allocate, the default being 1.
The optional ?-timeout timeout? arguments specifies the maximum time to wait for the handles to become available before raising an error (see ERROR HANDLING below for details on handling errors).
Requesting more than one handle in a single call (if more than one handle is required) is necessary as it is an error to request handles from a pool from which handles are already owned by the thread. This restriction is implemented to avoid possible deadlock conditions.
The handle returned by this command can be used as a scalar value for other ns_proxy commands, or it can be used as Tcl command itself (see ns_proxy eval for more information).
The proxy pool naming convention allows proxy worker to be started under different Unix UID/GID then the server itself. For that to work, the server must be running under root user (UID = 0). The naming convention is simple: pool_name:<optional_user_id>:<optional_group_id>.
For example, to start the proxy for the pool "mypool" with user UID of 100 the pool name can be constructed as: "mypool:100". To start the proxy with UID of 100 and group GID of 200: "mypool:100:200". Instead of numeric values user/group names can also be used.
Beware: if the main server is not running under privileged root user, the startup of the proxy under some alternative UID/GID may/will fail.
Returns list of all proxies allocated for the current interpreter.
This command sends a null request to the proxy specified by the handle argument. The proxy will be verified alive and restarted if necessary. This command is not normally required as the ns_proxy eval command will also verify and restart proxies as needed.
Returns a list of all currently defined proxy pools.
This command is alternate name for ns_proxy release.
Reads result from the script from the proxy specified by handle (see ERROR HANDLING below for details on handling errors).
Return the proxy handle to the pool. All handles owned by a thread to the corresponding pool must be returned before any handles can be allocated again. Within the server, a call to this routine is recommended for clarity but not strictly necessary. NaviServer installs a trace to release all handles at the end of every connection during interpreter deallocation.
Sends script to the proxy specified by handle. (see ERROR HANDLING below for details on handling errors).
Provide summative usage statistics in form of a dict from the specified pool. The dict contains the following keys: proxies, waiting, maxworkers, free, used, requests, processes, and runtime.
Stop all worker processes attached to running proxies for the given pool. If the optional handle is given, it stops the process only for that handle.
Waits for results from the proxy specified by handle. The optional timeout argument specifies a maximum time to wait for the command to complete before raising an error (see ERROR HANDLING below for details on handling errors).
Returns a list of the workers of the proxy pool, where every element contains a dict containing the following keys: id, pid, created, runs, and state. The command can be used for fine-tuing the number of workers for an application by checking their load. Creating workers at startup helps to keep the time of spawning low, especially when the memory footprint of the server is large and the server is running in a virtual machine. The value of created stands for the number of spawn operations for the workers.
All time units can be specified with and without a time unit suffix. Valid time units are "ms", "s", "m", "h", "d". If no time unit suffix is specified, seconds are assumed.
Errors generated by a script evaluated in a proxy interpreter are completely returned to the calling interpreter, including mapping the errorInfo and errorCode global variables from the proxy to the parent and raising a Tcl exception. This approach makes ns_proxy evaluations look very similar to the Tcl eval command.
Errors raised by a failure to communicate with the proxy process due to a timeout or unexpected process exit are also communicated back to the parent interpreter as Tcl exceptions. To distinguish between these cases, communication related errors set the errorCode global variable with the first element NSPROXY. The second element is one of the following:
The interpreter attempted to allocate handles from a pool from which it already owns one or more handles.
The worker program specified by the -exec program option could not be started.
The response from the proxy was invalid.
There was an error receiving the result from the worker process.
There was an error sending the script to the worker process.
Timeout while waiting to get a proxy handle from the pool.
Timeout while waiting for the response from the proxy process after sending the command for evaluation.
Requested too many proxy handles from the pool
Proxy is currently in the idle state.
Evaluation of the init script failed.
Proxy handle is currently not connected to any process.
Proxy handle is currently busy with the evaluation.
The default settings of the configuration parameters of ns_proxy can be provided in the configuration file of NaviServer.
# Loading the nxproxy module in the modules section
# of the server.
ns_section ns/server/${server}/modules {
# ...
ns_param nsproxy ${homedir}/bin/nsproxy.so
# ...
}
# Configuring the nsproxy module
ns_section ns/server/${server}/module/nsproxy {
# Proxy program to start
#ns_param exec ${homedir}/bin/nsproxy-helper
# Timeout when evaluating scripts
ns_param evaltimeout 0s
# Timeout when getting proxy handles
ns_param gettimeout 0s
# Timeout to send data
ns_param sendtimeout 5s
# Timeout to receive results
ns_param recvtimeout 5s
# Timeout to wait for workers to die
ns_param waittimeout 1s
# Timeout for a worker to live idle
ns_param idletimeout 5m
# log eval operations longer than this to the system log
ns_param logminduration 1s
# Max number of allowed workers alive
ns_param maxworkers 8
}
The following demonstrates sending a script to a remote proxy:
set handle [ns_proxy get myproxy]
ns_proxy eval $handle {info patchlevel}
ns_proxy release $handle
Alternatively, instead of using the scalar handle you can use the handle directly as a Tcl command:
set handle [ns_proxy get myproxy]
$handle {info patchlevel}
rename $handle ""
The following demonstrates using multiple proxies:
ns_proxy configure myproxy -maxworkers 10
set handles [ns_proxy get myproxy -handle 10]
foreach h $handles {
$h {puts "alive: [pid]"}
}
ns_proxy cleanup