---
name: "ns_job"
section: "3aolserver"
platform: "linux"
package: "aolserver4-dev"
version: "4.5.1-18.1"
release: "Debian 9 (Stretch)"
platforms: ["linux"]
url: "https://new.carta.tech/ns_job/3aolserver"
---

# ns\_job(3aolserver)

commands

```

```

## NAME

ns\_job - commands

## SYNOPSIS

**ns\_job** option ?*arg arg ...*?

**ns\_job** create *?-desc description? queueId ?maxthreads?*

**ns\_job** queue *?-detached? queueId  script*

**ns\_job** wait *?-timeout seconds:microseconds? queueId  jobId*

**ns\_job** waitany *?-timeout seconds:microseconds? queueId*

**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

**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.

## OPTIONS

**create**

create *?-desc description? queueId ?maxthreads?*

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

**queue**

queue *?-detached? 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* is true, then the job will be cleaned up when it completes; no wait will be necessary.

The new job's ID is returned.

**wait**

wait *?-timeout seconds:microseconds? queueId jobId*

Wait for the specified queued or running job to finish. *wait* returns the results of the script.

An error is thrown if the specified timeout period is reached.

**waitany**

waitany *?-timeout seconds:microseconds? queueId*

Wait for any job on the queue complete.

An error is thrown if the specified timeout period is reached.

**cancel**

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.

**delete**

delete *queueId*

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

**jobs**

jobs *queueId*

Return a list of the job IDs.

**queues**

Returns a list of the queues IDs.

**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.

**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.

**joblist**

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

id

Job's ID

state

scheduled

The job is schedule to run.

running

The job is currently running.

done

The job is 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.

Codes

 TCL\_OK\
  TCL\_ERROR\
  TCL\_RETURN\
  TCL\_BREAK\
  TCL\_CONTINUE

TYPE

 nondetached\
  detached

REQ

 none\
  wait\
  cancel

**genid**

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

## BUGS

## SEE ALSO

nsd(1), [info(n)](/info/n.md)

## KEYWORDS

ns\_job