NaviServer - programmable web server
4.99  5.0

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

ns_job(n) 5.0.0a naviserver "NaviServer Built-in Commands"

Name

ns_job - Implement job queues and thread pools for evaluating Tcl scripts

Table Of Contents

Synopsis

Description

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.

COMMANDS

ns_job cancel queueId jobId

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.

ns_job configure ?-jobsperthread N? ?-logminduration T? ?-timeout T?

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 parameter -logminduration defines a time limit for logging the system log. When a job takes longer than the time limit it will be logged.

Without any arguments, the command just returns current settings values in form of a dict.

ns_job create ?-desc description? queueId ?maxthreads?

Create a new job queue called queueId. If maxthreads is not specified, then the default of 4 is used.

ns_job delete queueId

Request that the specified queue be deleted. The queue will only be deleted when all jobs are removed.

ns_job exists queueId jobId

Returns 1 if such job is running the given queue, otherwise returns 0.

ns_job genid

Generate a new unique ID. This new ID can be used as the queue ID without conflicting with any other queue ID.

ns_job joblist queueId

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.

ns_job jobs queueId

Return a list of the job IDs.

ns_job queue ?-detached? ?-head? ?-jobid id? queueId script

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.

ns_job queuelist

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.

ns_job queues

Returns a list of the queue IDs.

ns_job threadlist

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.

ns_job wait ?-timeout T? queueId jobId

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 (given in seconds and fractions of seconds) is reached.

ns_job waitany ?-timeout T? queueId

Wait for any job on the queue complete.

An error is thrown if the specified timeout period (given in seconds and fractions of seconds) is reached.

CONFIGURATION

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.

EXAMPLES

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"}

See Also

ns_schedule_proc, nsd

Keywords

background, global built-in