NaviServer - programmable web server

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

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

## Name

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

## Table Of Contents

## Synopsis

- ns_job option ?arg arg ...?
- ns_job configure ?-jobsperthread N?
- ns_job create ?-desc description? queueId ?maxthreads?
- ns_job queue ?-detached? ?-jobid id? queueId script
- ns_job wait ?-timeout seconds:microseconds? queueId jobId
- ns_job waitany ?-timeout seconds:microseconds? queueId
- ns_job exists queueId jobId
- ns_job cancel queueId jobId
- ns_job delete queueId
- ns_job jobs queueId
- ns_job queues
- ns_job threadlist
- ns_job queuelist
- ns_job joblist queueId
- ns_job genid

## Description

ns_job manages a thread pool and a set of named "queues". Queues have a max number of threads and when the current number of running thread reaches "max" 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 option ?arg arg ...?

ns_job configure ?-jobsperthread N?

  Configures jobs system, parameters are: -jobsperthread defines how many jobs each thread can process and then gracefully exit, this works the same way as connsperthread config parameter for connection threads to help reduce memory consumption and cleanup Tcl resources.

  Without any arguments, the command just returns current settings values

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 queue ?-detached? ?-jobid id? queueId script

  Add a new job to 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 claned up when it completes; no wait will be necessary.

  if -jobid is specified, it will be used as new job id instead of auto-genereated one. If such job already exists, erro will be fired.

  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 wait ?-timeout seconds:microseconds? 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 is reached.

ns_job waitany ?-timeout seconds:microseconds? queueId

  Wait for any job on the queue complete. An error is thrown if the specified timeout period is reached.

ns_job exists queueId jobId

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

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. 1 (true) is returned if the job is currently running and can not be cancelled.

ns_job delete queueId

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

ns_job jobs queueId

  Return a list of the job IDs.

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 stop - The thread pools is being stopped. This probably means that the server is shutting down.

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 delete - Someone requested this queue be deleted. Queue will not be deleted until all the jobs on the queue are removed.

ns_job joblist queueId

  Returns a list the jobs in the specified queue. A job has the following fields:

  id - Job's ID

  state - The state of the job. The return values are as follows:

  scheduled - The job is scheduled to run.

  running - The job is currently running.

  done - The job has completed.

  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, cancel.

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.

## See Also

nsd