ns_job - Implement job queues and thread pools for evaluating Tcl scripts
ns_job manages a thread pool and a set of named job queues. Job queues have a max number of threads and when the current number of running thread reaches this maximum number then jobs are queued. New threads are created when there are less than maxthread number of idle threads.
This command provides a means for queueing Tcl scripts for evaluation by a pool of threads.
Remove the specified job from the queue. If the job is currently running, then the job will be removed from the queue when it completes. Returns 1 (true) if the job is currently running and can not be cancelled.
Configures jobs system, parameters are: -jobsperthread defines how many jobs each thread can process and then gracefully exit, performing a tcl-level cleanup. When the parameter is 0, which means that the number of jobs has no influence on cleaning up a thread). The logic works the same way as connsperthread config parameter for connection threads to help reduce memory consumption and cleanup Tcl resources.
The parameter -timeout defines maximum idle time for the job worker thread. When the timeout expires, the thread exits like when -jobsperthread runs out. When the -timeout is 0, the there will be no timeout. The value of -timeout can be specified in the form secs?:microsecs?, or secs.fraction, or as a number with a time unit.
The parameter -logminduration defines a time limit for logging the system log. When a job takes longer than the time limit it will be logged. The value can be specified in the form secs?:microsecs?, or secs.fraction, or as a number with a time unit.
Without any arguments, the command just returns current settings values in form of a dict.
Create a new job queue called queueId. If maxthreads is not specified, then the default of 4 is used.
Request that the specified queue be deleted. The queue will only be deleted when all jobs are removed.
Returns 1 if such job is running the given queue, otherwise returns 0.
Generate a new unique ID. This new ID can be used as the queue ID without conflicting with any other queue ID.
Returns a list the jobs in the specified queue. Every returned job entry has the following fields:
id - Job's ID
state - The job's state; either scheduled, running, done, or unknown.
script - The Tcl commands executed be the job.
results - If the job has completed, then this field will contain the results. If the job is running or scheduled to run, then this will contain the script.
code - When the job is done, this will contain the return code. Return codes are TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, TCL_CONTINUE.
type - The type of job. A job's return value is nondetached or detached.
req - The job is required. Return values are none, wait,or cancel.
thread - The thread id of the job.
starttime - The start time of the job.
endtime - The end time of the job.
Return a list of the job IDs.
Add a new job to the queue. When ?-head? is specified, add the new jab to the front of the queue. If there are less than maxthreads current running then the job will be started. If there are maxthreads currently running then this new job will be queued.
If -detached, then the job will be cleaned up when it completes; no wait will be necessary.
if -jobid is specified, it will be used as new job id instead of auto-generated one. If such job already exists, an error will be thrown.
if -head is specified, then new job will be inserted in the beginning of the joblist, otherwise and by default every new job is added to the end of the job list.
The new job's ID is returned.
Returns a list of the queues. A queue has the following fields:
name - Name of the queue.
desc - Description of the queue.
maxthreads - Max number of threads to run for this queue.
numrunning - Number of currently running jobs in this queue.
req - Some request fired; e.g. someone requested this queue be deleted. Queue will not be deleted until all the jobs on the queue are removed.
Returns a list of the queue IDs.
Returns a list of the thread pool's fields.
maxthreads - Max number of threads for all the queues in the thread pool.
numthreads - Number of allocated threads.
numidle - Number of currently idle threads.
req - E.g. stop: The thread pools is being stopped. This probably means that the server is shutting down.
Wait for the specified queued or running job to finish. ns_job wait returns the results of the script.
An error is thrown if the specified timeout period is reached. The value of -timeout can be specified in the form secs?:microsecs?, or secs.fraction, or as a number with a time unit.
Wait for any job on the queue complete.
An error is thrown if the specified timeout period is reached. The value of -timeout can be specified in the form secs?:microsecs?, or secs.fraction, or as a number with a time unit.
The default settings of the configuration parameters of ns_job can be provided in the global parameters of the NaviServer configuration file:
ns_section ns/parameters {
# ...
ns_param joblogminduration 1s
ns_param jobsperthread 1000
ns_param jobtimeout 5m
# ...
}
These configuration parameters define default values for the parameters which can be provided to ns_job configure.
Create a job queue, run a job in this queue and wait for the result.
% ns_job create q1
q1
% set j [ns_job queue q1 {
ns_log notice start
ns_sleep 10
ns_log notice stop
set x "i am done"}]
job0
% ns_job wait q1 $j
i am done
Run a job in this queue in the background and do not wait for the result.
% ns_job queue -detached q1 {ns_log notice "a detached job"}