NaviServer - programmable web server

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

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

## Name

ns_thread - Operate on threads

## Table Of Contents

## Synopsis

- ns_thread begin ?-name threadName? ?--? script
- ns_thread begindetached ?-name threadName? ?--? script
- ns_thread handle
- ns_thread id
- ns_thread name ?name?
- ns_thread stackinfo
- ns_thread wait handle
- ns_thread yield

## Description

This command provides a mechanism to manipulate threads. The legal options (which may be abbreviated) are:

## COMMANDS

ns_thread begin ?-name threadName? ?--? script

  Initializes a new thread and starts it executing script. When the option -name is specified, then the thread is named as "-tcl-$name:$nr-", where $nr is a counter to ensure unique names.

  Threads created this way are joinable and must be ns_thread joined, otherwise the resources held by the thread will not be freed until the thread is joined. Returns a handle to the new thread, which can be used in ns_thread wait.

ns_thread begindetached ?-name threadName? ?--? script

  Initializes a new thread and starts it executing script. Initializes a new thread and starts it executing script. When the option -name is specified, then the thread is named as "-tcl-$name:$nr-", where $nr is a counter to ensure unique names.

  Threads created this way are detached and do not need to be (nor can be) joined (no thread can wait for this thread). In contrary to ns_thread begin this command returns an empty result.

ns_thread handle

  Returns the handle for the current thread.

ns_thread id

  Returns the current thread's thread ID as an integer. This thread ID corresponds to the third element in the sub-list returned from ns_info threads.

ns_thread name ?name?

  Returns the name of the current thread. Optionally sets the thread name if name is specified.

ns_thread stackinfo

  Returns the maximum available size of the C stack and the currently free size of the C stack from the current thread in a form usable for "array set". For example the command might return "max 2048000 free 2024408"

ns_thread wait handle

  Attempts to wait for the the thread with the specified handle. If the thread is still executing, the caller will block until the thread being joined completes. Returns the return value of the script that the thread being joined was executing.

  NOTE: Calling ns_thread wait on an invalid handle or a handle that has already been waited for will cause the server to abort with a fatal error.

ns_thread yield

  Causes the current thread to yield its CPU to other running threads.

## See Also

ns_info

## Keywords

stack, thread