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)

KEYWORDS

       ns_job