ag/cpython-source-deps
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Import Tcl 8.6.12

Browse Source
This commit is contained in:
Steve Dower
2021-11-08 17:30:58 +00:00
parent 1aadb2455c
commit 674867e7e6
608 changed files with 78089 additions and 60360 deletions
Download Patch File Download Diff File Expand all files Collapse all files

863
pkgs/thread2.8.7/doc/man/thread.n Normal file
View File

@@ -0,0 +1,863 @@
'\"
'\" Generated from file '' by tcllib/doctools with format 'nroff'
'\"
.TH "thread" n 2\&.8 "Tcl Threading"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\" Start paragraph describing an argument to a library procedure.
.\" type is type of argument (int, etc.), in/out is either "in", "out",
.\" or "in/out" to describe whether procedure reads or modifies arg,
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
.\" needed; use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\" Give maximum sizes of arguments for setting tab stops. Type and
.\" name are examples of largest possible arguments that will be passed
.\" to .AP later. If args are omitted, default tab stops are used.
.\"
.\" .BS
.\" Start box enclosure. From here until next .BE, everything will be
.\" enclosed in one large box.
.\"
.\" .BE
.\" End of box enclosure.
.\"
.\" .CS
.\" Begin code excerpt.
.\"
.\" .CE
.\" End code excerpt.
.\"
.\" .VS ?version? ?br?
.\" Begin vertical sidebar, for use in marking newly-changed parts
.\" of man pages. The first argument is ignored and used for recording
.\" the version when the .VS was added, so that the sidebars can be
.\" found and removed when they reach a certain age. If another argument
.\" is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\" End of vertical sidebar.
.\"
.\" .DS
.\" Begin an indented unfilled display.
.\"
.\" .DE
.\" End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\" Start of list of standard options for a Tk widget. The manpage
.\" argument defines where to look up the standard options; if
.\" omitted, defaults to "options". The options follow on successive
.\" lines, in three columns separated by tabs.
.\"
.\" .SE
.\" End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\" Start of description of a specific option. cmdName gives the
.\" option's name as specified in the class command, dbName gives
.\" the option's name in the option database, and dbClass gives
.\" the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\" Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
.\" (for trailing punctuation) and then a closing parenthesis.
.\"
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\" # BS - start boxed text
.\" # ^y = starting y location
.\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\" # VS - start vertical sidebar
.\" # ^Y = starting y location
.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\" # Special macro to handle page bottom: finish off current
.\" # box/sidebar if in box/sidebar mode, then invoked standard
.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
.\" # DE - end display
.de DE
.fi
.RE
.sp
..
.\" # SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\" # CE - end code excerpt
.de CE
.fi
.RE
..
.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\" # QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\" # PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\" # QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\" # MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
thread \- Extension for script access to Tcl threading
.SH SYNOPSIS
package require \fBTcl 8\&.4\fR
.sp
package require \fBThread ?2\&.8?\fR
.sp
\fBthread::create\fR ?-joinable? ?-preserved? ?script?
.sp
\fBthread::preserve\fR ?id?
.sp
\fBthread::release\fR ?-wait? ?id?
.sp
\fBthread::id\fR
.sp
\fBthread::errorproc\fR ?procname?
.sp
\fBthread::cancel\fR ?-unwind? \fIid\fR ?result?
.sp
\fBthread::unwind\fR
.sp
\fBthread::exit\fR ?status?
.sp
\fBthread::names\fR
.sp
\fBthread::exists\fR \fIid\fR
.sp
\fBthread::send\fR ?-async? ?-head? \fIid\fR \fIscript\fR ?varname?
.sp
\fBthread::broadcast\fR \fIscript\fR
.sp
\fBthread::wait\fR
.sp
\fBthread::eval\fR ?-lock mutex? \fIarg\fR ?arg \&.\&.\&.?
.sp
\fBthread::join\fR \fIid\fR
.sp
\fBthread::configure\fR \fIid\fR ?option? ?value? ?\&.\&.\&.?
.sp
\fBthread::transfer\fR \fIid\fR \fIchannel\fR
.sp
\fBthread::detach\fR \fIchannel\fR
.sp
\fBthread::attach\fR \fIchannel\fR
.sp
\fBthread::mutex\fR
.sp
\fBthread::mutex\fR \fBcreate\fR ?-recursive?
.sp
\fBthread::mutex\fR \fBdestroy\fR \fImutex\fR
.sp
\fBthread::mutex\fR \fBlock\fR \fImutex\fR
.sp
\fBthread::mutex\fR \fBunlock\fR \fImutex\fR
.sp
\fBthread::rwmutex\fR
.sp
\fBthread::rwmutex\fR \fBcreate\fR
.sp
\fBthread::rwmutex\fR \fBdestroy\fR \fImutex\fR
.sp
\fBthread::rwmutex\fR \fBrlock\fR \fImutex\fR
.sp
\fBthread::rwmutex\fR \fBwlock\fR \fImutex\fR
.sp
\fBthread::rwmutex\fR \fBunlock\fR \fImutex\fR
.sp
\fBthread::cond\fR
.sp
\fBthread::cond\fR \fBcreate\fR
.sp
\fBthread::cond\fR \fBdestroy\fR \fIcond\fR
.sp
\fBthread::cond\fR \fBnotify\fR \fIcond\fR
.sp
\fBthread::cond\fR \fBwait\fR \fIcond\fR \fImutex\fR ?ms?
.sp
.BE
.SH DESCRIPTION
The \fBthread\fR extension creates threads that contain Tcl
interpreters, and it lets you send scripts to those threads for
evaluation\&.
Additionally, it provides script-level access to basic thread
synchronization primitives, like mutexes and condition variables\&.
.SH COMMANDS
This section describes commands for creating and destroying threads
and sending scripts to threads for evaluation\&.
.TP
\fBthread::create\fR ?-joinable? ?-preserved? ?script?
This command creates a thread that contains a Tcl interpreter\&.
The Tcl interpreter either evaluates the optional \fBscript\fR, if
specified, or it waits in the event loop for scripts that arrive via
the \fBthread::send\fR command\&. Both of them would take place simultaneously
with the return of command \fBthread::create\fR to the caller thread\&.
Neither the caller is waiting for the finishing of optional \fBscript\fR,
nor the result, if any, of the \fBscript\fR is returned to the caller\&.
The result of \fBthread::create\fR is the ID of the thread\&. This is
the opaque handle which identifies the newly created thread for
all other package commands\&. The handle of the thread goes out of scope
automatically when thread is marked for exit
(see the \fBthread::release\fR command below)\&.
.sp
If the optional \fBscript\fR argument contains the \fBthread::wait\fR
command the thread will enter into the event loop\&. If such command is not
found in the \fBscript\fR the thread will run the \fBscript\fR to
the end and exit\&. In that case, the handle may be safely ignored since it
refers to a thread which does not exists any more at the time when the
command returns\&.
.sp
Using flag \fB-joinable\fR it is possible to create a joinable
thread, i\&.e\&. one upon whose exit can be waited upon by using
\fBthread::join\fR command\&.
Note that failure to join a thread created with \fB-joinable\fR flag
results in resource and memory leaks\&.
.sp
Threads created by the \fBthread::create\fR cannot be destroyed
forcefully\&. Consequently, there is no corresponding thread destroy
command\&. A thread may only be released using the \fBthread::release\fR
and if its internal reference count drops to zero, the thread is
marked for exit\&. This kicks the thread out of the event loop
servicing and the thread continues to execute commands passed in
the \fBscript\fR argument, following the \fBthread::wait\fR
command\&. If this was the last command in the script, as usually the
case, the thread will exit\&.
.sp
It is possible to create a situation in which it may be impossible
to terminate the thread, for example by putting some endless loop
after the \fBthread::wait\fR or entering the event loop again by
doing an vwait-type of command\&. In such cases, the thread may never
exit\&. This is considered to be a bad practice and should be avoided
if possible\&. This is best illustrated by the example below:
.CS
# You should never do \&.\&.\&.
set tid [thread::create {
package require Http
thread::wait
vwait forever ; # <-- this!
}]
.CE
.IP
The thread created in the above example will never be able to exit\&.
After it has been released with the last matching \fBthread::release\fR
call, the thread will jump out of the \fBthread::wait\fR and continue
to execute commands following\&. It will enter \fBvwait\fR command and
wait endlessly for events\&. There is no way one can terminate such thread,
so you wouldn't want to do this!
.sp
Each newly created has its internal reference counter set to 0 (zero),
i\&.e\&. it is unreserved\&. This counter gets incremented by a call to
\fBthread::preserve\fR and decremented by a call to \fBthread::release\fR
command\&. These two commands implement simple but effective thread
reservation system and offer predictable and controllable thread
termination capabilities\&. It is however possible to create initially
preserved threads by using flag \fB-preserved\fR of the
\fBthread::create\fR command\&. Threads created with this flag have the
initial value of the reference counter of 1 (one), and are thus
initially marked reserved\&.
.TP
\fBthread::preserve\fR ?id?
This command increments the thread reference counter\&. Each call
to this command increments the reference counter by one (1)\&.
Command returns the value of the reference counter after the increment\&.
If called with the optional thread \fBid\fR, the command preserves
the given thread\&. Otherwise the current thread is preserved\&.
.sp
With reference counting, one can implement controlled access to a
shared Tcl thread\&. By incrementing the reference counter, the
caller signalizes that he/she wishes to use the thread for a longer
period of time\&. By decrementing the counter, caller signalizes that
he/she has finished using the thread\&.
.TP
\fBthread::release\fR ?-wait? ?id?
This command decrements the thread reference counter\&. Each call to
this command decrements the reference counter by one (1)\&.
If called with the optional thread \fBid\fR, the command releases
the given thread\&. Otherwise, the current thread is released\&.
Command returns the value of the reference counter after the decrement\&.
When the reference counter reaches zero (0), the target thread is
marked for termination\&. You should not reference the thread after the
\fBthread::release\fR command returns zero or negative integer\&.
The handle of the thread goes out of scope and should not be used any
more\&. Any following reference to the same thread handle will result
in Tcl error\&.
.sp
Optional flag \fB-wait\fR instructs the caller thread to wait for
the target thread to exit, if the effect of the command would result
in termination of the target thread, i\&.e\&. if the return result would
be zero (0)\&. Without the flag, the caller thread does not wait for
the target thread to exit\&. Care must be taken when using the
\fB-wait\fR, since this may block the caller thread indefinitely\&.
This option has been implemented for some special uses of the extension
and is deprecated for regular use\&. Regular users should create joinable
threads by using the \fB-joinable\fR option of the \fBthread::create\fR
command and the \fBthread::join\fR to wait for thread to exit\&.
.TP
\fBthread::id\fR
This command returns the ID of the current thread\&.
.TP
\fBthread::errorproc\fR ?procname?
This command sets a handler for errors that occur in scripts sent
asynchronously, using the \fB-async\fR flag of the
\fBthread::send\fR command, to other threads\&. If no handler
is specified, the current handler is returned\&. The empty string
resets the handler to default (unspecified) value\&.
An uncaught error in a thread causes an error message to be sent
to the standard error channel\&. This default reporting scheme can
be changed by registering a procedure which is called to report
the error\&. The \fIprocname\fR is called in the interpreter that
invoked the \fBthread::errorproc\fR command\&. The \fIprocname\fR
is called like this:
.CS
myerrorproc thread_id errorInfo
.CE
.TP
\fBthread::cancel\fR ?-unwind? \fIid\fR ?result?
This command requires Tcl version 8\&.6 or higher\&.
.sp
Cancels the script being evaluated in the thread given by the \fIid\fR
parameter\&. Without the \fB-unwind\fR switch the evaluation stack for
the interpreter is unwound until an enclosing catch command is found or
there are no further invocations of the interpreter left on the call
stack\&. With the \fB-unwind\fR switch the evaluation stack for the
interpreter is unwound without regard to any intervening catch command
until there are no further invocations of the interpreter left on the
call stack\&. If \fIresult\fR is present, it will be used as the error
message string; otherwise, a default error message string will be used\&.
.TP
\fBthread::unwind\fR
Use of this command is deprecated in favour of more advanced thread
reservation system implemented with \fBthread::preserve\fR and
\fBthread::release\fR commands\&. Support for \fBthread::unwind\fR
command will disappear in some future major release of the extension\&.
.sp
This command stops a prior \fBthread::wait\fR command\&. Execution of
the script passed to newly created thread will continue from the
\fBthread::wait\fR command\&. If \fBthread::wait\fR was the last command
in the script, the thread will exit\&. The command returns empty result
but may trigger Tcl error with the message "target thread died" in some
situations\&.
.TP
\fBthread::exit\fR ?status?
Use of this command is deprecated in favour of more advanced thread
reservation system implemented with \fBthread::preserve\fR and
\fBthread::release\fR commands\&. Support for \fBthread::exit\fR
command will disappear in some future major release of the extension\&.
.sp
This command forces a thread stuck in the \fBthread::wait\fR command to
unconditionally exit\&. The thread's exit status defaults to 666 and can be
specified using the optional \fIstatus\fR argument\&. The execution of
\fBthread::exit\fR command is guaranteed to leave the program memory in the
inconsistent state, produce memory leaks and otherwise affect other subsystem(s)
of the Tcl application in an unpredictable manner\&. The command returns empty
result but may trigger Tcl error with the message "target thread died" in some
situations\&.
.TP
\fBthread::names\fR
This command returns a list of thread IDs\&. These are only for
threads that have been created via \fBthread::create\fR command\&.
If your application creates other threads at the C level, they
are not reported by this command\&.
.TP
\fBthread::exists\fR \fIid\fR
Returns true (1) if thread given by the \fIid\fR parameter exists,
false (0) otherwise\&. This applies only for threads that have
been created via \fBthread::create\fR command\&.
.TP
\fBthread::send\fR ?-async? ?-head? \fIid\fR \fIscript\fR ?varname?
This command passes a \fIscript\fR to another thread and, optionally,
waits for the result\&. If the \fB-async\fR flag is specified, the
command does not wait for the result and it returns empty string\&.
The target thread must enter it's event loop in order to receive
scripts sent via this command\&. This is done by default for threads
created without a startup script\&. Threads can enter the event loop
explicitly by calling \fBthread::wait\fR or any other relevant Tcl/Tk
command, like \fBupdate\fR, \fBvwait\fR, etc\&.
.sp
Optional \fBvarname\fR specifies name of the variable to store
the result of the \fIscript\fR\&. Without the \fB-async\fR flag,
the command returns the evaluation code, similarly to the standard
Tcl \fBcatch\fR command\&. If, however, the \fB-async\fR flag is
specified, the command returns immediately and caller can later
\fBvwait\fR on ?varname? to get the result of the passed \fIscript\fR
.CS
set t1 [thread::create]
set t2 [thread::create]
thread::send -async $t1 "set a 1" result
thread::send -async $t2 "set b 2" result
for {set i 0} {$i < 2} {incr i} {
vwait result
}
.CE
.IP
In the above example, two threads were fed work and both of them were
instructed to signalize the same variable "result" in the calling thread\&.
The caller entered the event loop twice to get both results\&. Note,
however, that the order of the received results may vary, depending on
the current system load, type of work done, etc, etc\&.
.sp
Many threads can simultaneously send scripts to the target thread for
execution\&. All of them are entered into the event queue of the target
thread and executed on the FIFO basis, intermingled with optional other
events pending in the event queue of the target thread\&.
Using the optional ?-head? switch, scripts posted to the thread's
event queue can be placed on the head, instead on the tail of the queue,
thus being executed in the LIFO fashion\&.
.TP
\fBthread::broadcast\fR \fIscript\fR
This command passes a \fIscript\fR to all threads created by the
package for execution\&. It does not wait for response from any of
the threads\&.
.TP
\fBthread::wait\fR
This enters the event loop so a thread can receive messages from
the \fBthread::send\fR command\&. This command should only be used
within the script passed to the \fBthread::create\fR\&. It should
be the very last command in the script\&. If this is not the case,
the exiting thread will continue executing the script lines past
the \fBthread::wait\fR which is usually not what you want and/or
expect\&.
.CS
set t1 [thread::create {
#
# Do some initialization work here
#
thread::wait ; # Enter the event loop
}]
.CE
.TP
\fBthread::eval\fR ?-lock mutex? \fIarg\fR ?arg \&.\&.\&.?
This command concatenates passed arguments and evaluates the
resulting script under the mutex protection\&. If no mutex is
specified by using the ?-lock mutex? optional argument,
the internal static mutex is used\&.
.TP
\fBthread::join\fR \fIid\fR
This command waits for the thread with ID \fIid\fR to exit and
then returns it's exit code\&. Errors will be returned for threads
which are not joinable or already waited upon by another thread\&.
Upon the join the handle of the thread has gone out of scope and
should not be used any more\&.
.TP
\fBthread::configure\fR \fIid\fR ?option? ?value? ?\&.\&.\&.?
This command configures various low-level aspects of the thread with
ID \fIid\fR in the similar way as the standard Tcl command
\fBfconfigure\fR configures some Tcl channel options\&. Options currently
supported are: \fB-eventmark\fR and \fB-unwindonerror\fR\&.
.sp
When \fB-eventmark\fR is provided with a value greater than 0 (zero), that
value is the maximum number of asynchronously posted scripts that may be
pending for the thread\&. \fBthread::send -async\fR blocks until the number of
pending scripts in the event loop drops below the \fB-eventmark\fR value\&.
.sp
When \fB-unwindonerror\fR is provided with a value of true, an error result
in a script causes the thread to unwind, making it unavailable to evaluate
additional scripts\&.
.TP
\fBthread::transfer\fR \fIid\fR \fIchannel\fR
This moves the specified \fIchannel\fR from the current thread
and interpreter to the main interpreter of the thread with the
given \fIid\fR\&. After the move the current interpreter has no
access to the channel any more, but the main interpreter of the
target thread will be able to use it from now on\&.
The command waits until the other thread has incorporated the
channel\&. Because of this it is possible to deadlock the
participating threads by commanding the other through a
synchronous \fBthread::send\fR to transfer a channel to us\&.
This easily extends into longer loops of threads waiting for
each other\&. Other restrictions: the channel in question must
not be shared among multiple interpreters running in the
sending thread\&. This automatically excludes the special channels
for standard input, output and error\&.
.sp
Due to the internal Tcl core implementation and the restriction on
transferring shared channels, one has to take extra measures when
transferring socket channels created by accepting the connection
out of the \fBsocket\fR commands callback procedures:
.CS
socket -server _Accept 2200
proc _Accept {s ipaddr port} {
after idle [list Accept $s $ipaddr $port]
}
proc Accept {s ipaddr port} {
set tid [thread::create]
thread::transfer $tid $s
}
.CE
.TP
\fBthread::detach\fR \fIchannel\fR
This detaches the specified \fIchannel\fR from the current thread and
interpreter\&. After that, the current interpreter has no access to the
channel any more\&. The channel is in the parked state until some other
(or the same) thread attaches the channel again with \fBthread::attach\fR\&.
Restrictions: same as for transferring shared channels with the
\fBthread::transfer\fR command\&.
.TP
\fBthread::attach\fR \fIchannel\fR
This attaches the previously detached \fIchannel\fR in the
current thread/interpreter\&. For already existing channels,
the command does nothing, i\&.e\&. it is not an error to attach the
same channel more than once\&. The first operation will actually
perform the operation, while all subsequent operation will just
do nothing\&. Command throws error if the \fIchannel\fR cannot be
found in the list of detached channels and/or in the current
interpreter\&.
.TP
\fBthread::mutex\fR
Mutexes are most common thread synchronization primitives\&.
They are used to synchronize access from two or more threads to one or
more shared resources\&. This command provides script-level access to
exclusive and/or recursive mutexes\&. Exclusive mutexes can be locked
only once by one thread, while recursive mutexes can be locked many
times by the same thread\&. For recursive mutexes, number of lock and
unlock operations must match, otherwise, the mutex will never be
released, which would lead to various deadlock situations\&.
.sp
Care has to be taken when using mutexes in an multithreading program\&.
Improper use of mutexes may lead to various deadlock situations,
especially when using exclusive mutexes\&.
.sp
The \fBthread::mutex\fR command supports following subcommands and options:
.RS
.TP
\fBthread::mutex\fR \fBcreate\fR ?-recursive?
Creates the mutex and returns it's opaque handle\&. This handle
should be used for any future reference to the newly created mutex\&.
If no optional ?-recursive? argument was specified, the command
creates the exclusive mutex\&. With the ?-recursive? argument,
the command creates a recursive mutex\&.
.TP
\fBthread::mutex\fR \fBdestroy\fR \fImutex\fR
Destroys the \fImutex\fR\&. Mutex should be in unlocked state before
the destroy attempt\&. If the mutex is locked, the command will throw
Tcl error\&.
.TP
\fBthread::mutex\fR \fBlock\fR \fImutex\fR
Locks the \fImutex\fR\&. Locking the exclusive mutex may throw Tcl
error if on attempt to lock the same mutex twice from the same
thread\&. If your program logic forces you to lock the same mutex
twice or more from the same thread (this may happen in recursive
procedure invocations) you should consider using the recursive mutexes\&.
.TP
\fBthread::mutex\fR \fBunlock\fR \fImutex\fR
Unlocks the \fImutex\fR so some other thread may lock it again\&.
Attempt to unlock the already unlocked mutex will throw Tcl error\&.
.RE
.sp
.TP
\fBthread::rwmutex\fR
This command creates many-readers/single-writer mutexes\&. Reader/writer
mutexes allow you to serialize access to a shared resource more optimally\&.
In situations where a shared resource gets mostly read and seldom modified,
you might gain some performance by using reader/writer mutexes instead of
exclusive or recursive mutexes\&.
.sp
For reading the resource, thread should obtain a read lock on the resource\&.
Read lock is non-exclusive, meaning that more than one thread can
obtain a read lock to the same resource, without waiting on other readers\&.
For changing the resource, however, a thread must obtain a exclusive
write lock\&. This lock effectively blocks all threads from gaining the
read-lock while the resource is been modified by the writer thread\&.
Only after the write lock has been released, the resource may be read-locked
again\&.
.sp
The \fBthread::rwmutex\fR command supports following subcommands and options:
.RS
.TP
\fBthread::rwmutex\fR \fBcreate\fR
Creates the reader/writer mutex and returns it's opaque handle\&.
This handle should be used for any future reference to the newly
created mutex\&.
.TP
\fBthread::rwmutex\fR \fBdestroy\fR \fImutex\fR
Destroys the reader/writer \fImutex\fR\&. If the mutex is already locked,
attempt to destroy it will throw Tcl error\&.
.TP
\fBthread::rwmutex\fR \fBrlock\fR \fImutex\fR
Locks the \fImutex\fR for reading\&. More than one thread may read-lock
the same \fImutex\fR at the same time\&.
.TP
\fBthread::rwmutex\fR \fBwlock\fR \fImutex\fR
Locks the \fImutex\fR for writing\&. Only one thread may write-lock
the same \fImutex\fR at the same time\&. Attempt to write-lock same
\fImutex\fR twice from the same thread will throw Tcl error\&.
.TP
\fBthread::rwmutex\fR \fBunlock\fR \fImutex\fR
Unlocks the \fImutex\fR so some other thread may lock it again\&.
Attempt to unlock already unlocked \fImutex\fR will throw Tcl error\&.
.RE
.sp
.TP
\fBthread::cond\fR
This command provides script-level access to condition variables\&.
A condition variable creates a safe environment for the program
to test some condition, sleep on it when false and be awakened
when it might have become true\&. A condition variable is always
used in the conjunction with an exclusive mutex\&. If you attempt
to use other type of mutex in conjunction with the condition
variable, a Tcl error will be thrown\&.
.sp
The command supports following subcommands and options:
.RS
.TP
\fBthread::cond\fR \fBcreate\fR
Creates the condition variable and returns it's opaque handle\&.
This handle should be used for any future reference to newly
created condition variable\&.
.TP
\fBthread::cond\fR \fBdestroy\fR \fIcond\fR
Destroys condition variable \fIcond\fR\&. Extreme care has to be taken
that nobody is using (i\&.e\&. waiting on) the condition variable,
otherwise unexpected errors may happen\&.
.TP
\fBthread::cond\fR \fBnotify\fR \fIcond\fR
Wakes up all threads waiting on the condition variable \fIcond\fR\&.
.TP
\fBthread::cond\fR \fBwait\fR \fIcond\fR \fImutex\fR ?ms?
This command is used to suspend program execution until the condition
variable \fIcond\fR has been signalled or the optional timer has expired\&.
The exclusive \fImutex\fR must be locked by the calling thread on entrance
to this command\&. If the mutex is not locked, Tcl error is thrown\&.
While waiting on the \fIcond\fR, the command releases \fImutex\fR\&.
Before returning to the calling thread, the command re-acquires the
\fImutex\fR again\&. Unlocking the \fImutex\fR and waiting on the
condition variable \fIcond\fR is done atomically\&.
.sp
The \fBms\fR command option, if given, must be an integer specifying
time interval in milliseconds the command waits to be signalled\&.
Otherwise the command waits on condition notify forever\&.
.sp
In multithreading programs, there are many situations where a thread has
to wait for some event to happen until it is allowed to proceed\&.
This is usually accomplished by repeatedly testing a condition under the
mutex protection and waiting on the condition variable until the condition
evaluates to true:
.CS
set mutex [thread::mutex create]
set cond [thread::cond create]
thread::mutex lock $mutex
while {<some_condition_is_true>} {
thread::cond wait $cond $mutex
}
# Do some work under mutex protection
thread::mutex unlock $mutex
.CE
.IP
Repeated testing of the condition is needed since the condition variable
may get signalled without the condition being actually changed (spurious
thread wake-ups, for example)\&.
.RE
.PP
.SH DISCUSSION
The fundamental threading model in Tcl is that there can be one or
more Tcl interpreters per thread, but each Tcl interpreter should
only be used by a single thread which created it\&.
A "shared memory" abstraction is awkward to provide in Tcl because
Tcl makes assumptions about variable and data ownership\&. Therefore
this extension supports a simple form of threading where the main
thread can manage several background, or "worker" threads\&.
For example, an event-driven server can pass requests to worker
threads, and then await responses from worker threads or new client
requests\&. Everything goes through the common Tcl event loop, so
message passing between threads works naturally with event-driven I/O,
\fBvwait\fR on variables, and so forth\&. For the transfer of bulk
information it is possible to move channels between the threads\&.
.PP
For advanced multithreading scripts, script-level access to two
basic synchronization primitives, mutex and condition variables,
is also supported\&.
.SH "SEE ALSO"
\fIhttp://www\&.tcl\&.tk/doc/howto/thread_model\&.html\fR, tpool, tsv, ttrace
.SH KEYWORDS
events, message passing, mutex, synchronization, thread

496
pkgs/thread2.8.7/doc/man/tpool.n Normal file
View File

@@ -0,0 +1,496 @@
'\"
'\" Generated from file '' by tcllib/doctools with format 'nroff'
'\"
.TH "tpool" n 2\&.8 "Tcl Threading"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\" Start paragraph describing an argument to a library procedure.
.\" type is type of argument (int, etc.), in/out is either "in", "out",
.\" or "in/out" to describe whether procedure reads or modifies arg,
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
.\" needed; use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\" Give maximum sizes of arguments for setting tab stops. Type and
.\" name are examples of largest possible arguments that will be passed
.\" to .AP later. If args are omitted, default tab stops are used.
.\"
.\" .BS
.\" Start box enclosure. From here until next .BE, everything will be
.\" enclosed in one large box.
.\"
.\" .BE
.\" End of box enclosure.
.\"
.\" .CS
.\" Begin code excerpt.
.\"
.\" .CE
.\" End code excerpt.
.\"
.\" .VS ?version? ?br?
.\" Begin vertical sidebar, for use in marking newly-changed parts
.\" of man pages. The first argument is ignored and used for recording
.\" the version when the .VS was added, so that the sidebars can be
.\" found and removed when they reach a certain age. If another argument
.\" is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\" End of vertical sidebar.
.\"
.\" .DS
.\" Begin an indented unfilled display.
.\"
.\" .DE
.\" End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\" Start of list of standard options for a Tk widget. The manpage
.\" argument defines where to look up the standard options; if
.\" omitted, defaults to "options". The options follow on successive
.\" lines, in three columns separated by tabs.
.\"
.\" .SE
.\" End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\" Start of description of a specific option. cmdName gives the
.\" option's name as specified in the class command, dbName gives
.\" the option's name in the option database, and dbClass gives
.\" the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\" Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
.\" (for trailing punctuation) and then a closing parenthesis.
.\"
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\" # BS - start boxed text
.\" # ^y = starting y location
.\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\" # VS - start vertical sidebar
.\" # ^Y = starting y location
.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\" # Special macro to handle page bottom: finish off current
.\" # box/sidebar if in box/sidebar mode, then invoked standard
.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
.\" # DE - end display
.de DE
.fi
.RE
.sp
..
.\" # SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\" # CE - end code excerpt
.de CE
.fi
.RE
..
.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\" # QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\" # PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\" # QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\" # MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tpool \- Part of the Tcl threading extension implementing pools of worker threads\&.
.SH SYNOPSIS
package require \fBTcl 8\&.4\fR
.sp
package require \fBThread ?2\&.8?\fR
.sp
\fBtpool::create\fR ?options?
.sp
\fBtpool::names\fR
.sp
\fBtpool::post\fR ?-detached? ?-nowait? \fItpool\fR \fIscript\fR
.sp
\fBtpool::wait\fR \fItpool\fR \fIjoblist\fR ?varname?
.sp
\fBtpool::cancel\fR \fItpool\fR \fIjoblist\fR ?varname?
.sp
\fBtpool::get\fR \fItpool\fR \fIjob\fR
.sp
\fBtpool::preserve\fR \fItpool\fR
.sp
\fBtpool::release\fR \fItpool\fR
.sp
\fBtpool::suspend\fR \fItpool\fR
.sp
\fBtpool::resume\fR \fItpool\fR
.sp
.BE
.SH DESCRIPTION
This package creates and manages pools of worker threads\&. It allows you
to post jobs to worker threads and wait for their completion\&. The
threadpool implementation is Tcl event-loop aware\&. That means that any
time a caller is forced to wait for an event (job being completed or
a worker thread becoming idle or initialized), the implementation will
enter the event loop and allow for servicing of other pending file or
timer (or any other supported) events\&.
.SH COMMANDS
.TP
\fBtpool::create\fR ?options?
This command creates new threadpool\&. It accepts several options as
key-value pairs\&. Options are used to tune some threadpool parameters\&.
The command returns the ID of the newly created threadpool\&.
.sp
Following options are supported:
.RS
.TP
\fB-minworkers\fR \fInumber\fR
Minimum number of worker threads needed for this threadpool instance\&.
During threadpool creation, the implementation will create somany
worker threads upfront and will keep at least number of them alive
during the lifetime of the threadpool instance\&.
Default value of this parameter is 0 (zero)\&. which means that a newly
threadpool will have no worker threads initialy\&. All worker threads
will be started on demand by callers running \fBtpool::post\fR command
and posting jobs to the job queue\&.
.TP
\fB-maxworkers\fR \fInumber\fR
Maximum number of worker threads allowed for this threadpool instance\&.
If a new job is pending and there are no idle worker threads available,
the implementation will try to create new worker thread\&. If the number
of available worker threads is lower than the given number,
new worker thread will start\&. The caller will automatically enter the
event loop and wait until the worker thread has initialized\&. If\&. however,
the number of available worker threads is equal to the given number,
the caller will enter the event loop and wait for the first worker thread
to get idle, thus ready to run the job\&.
Default value of this parameter is 4 (four), which means that the
threadpool instance will allow maximum of 4 worker threads running jobs
or being idle waiting for new jobs to get posted to the job queue\&.
.TP
\fB-idletime\fR \fIseconds\fR
Time in seconds an idle worker thread waits for the job to get posted
to the job queue\&. If no job arrives during this interval and the time
expires, the worker thread will check the number of currently available
worker threads and if the number is higher than the number set by the
\fBminthreads\fR option, it will exit\&.
If an \fBexitscript\fR has been defined, the exiting worker thread
will first run the script and then exit\&. Errors from the exit script,
if any, are ignored\&.
.sp
The idle worker thread is not servicing the event loop\&. If you, however,
put the worker thread into the event loop, by evaluating the
\fBvwait\fR or other related Tcl commands, the worker thread
will not be in the idle state, hence the idle timer will not be
taken into account\&.
Default value for this option is unspecified\&.
.TP
\fB-initcmd\fR \fIscript\fR
Sets a Tcl script used to initialize new worker thread\&. This is usually
used to load packages and commands in the worker, set default variables,
create namespaces, and such\&. If the passed script runs into a Tcl error,
the worker will not be created and the initiating command (either the
\fBtpool::create\fR or \fBtpool::post\fR) will throw error\&.
Default value for this option is unspecified, hence, the Tcl interpreter of
the worker thread will contain just the initial set of Tcl commands\&.
.TP
\fB-exitcmd\fR \fIscript\fR
Sets a Tcl script run when the idle worker thread exits\&. This is normaly
used to cleanup the state of the worker thread, release reserved resources,
cleanup memory and such\&.
Default value for this option is unspecified, thus no Tcl script will run
on the worker thread exit\&.
.RE
.sp
.TP
\fBtpool::names\fR
This command returns a list of IDs of threadpools created with the
\fBtpool::create\fR command\&. If no threadpools were found, the
command will return empty list\&.
.TP
\fBtpool::post\fR ?-detached? ?-nowait? \fItpool\fR \fIscript\fR
This command sends a \fIscript\fR to the target \fItpool\fR threadpool
for execution\&. The script will be executed in the first available idle
worker thread\&. If there are no idle worker threads available, the command
will create new one, enter the event loop and service events until the
newly created thread is initialized\&. If the current number of worker
threads is equal to the maximum number of worker threads, as defined
during the threadpool creation, the command will enter the event loop and
service events while waiting for one of the worker threads to become idle\&.
If the optional ?-nowait? argument is given, the command will not wait
for one idle worker\&. It will just place the job in the pool's job queue
and return immediately\&.
.sp
The command returns the ID of the posted job\&. This ID is used for subsequent
\fBtpool::wait\fR, \fBtpool::get\fR and \fBtpool::cancel\fR commands to wait
for and retrieve result of the posted script, or cancel the posted job
respectively\&. If the optional ?-detached? argument is specified, the
command will post a detached job\&. A detached job can not be cancelled or
waited upon and is not identified by the job ID\&.
.sp
If the threadpool \fItpool\fR is not found in the list of active
thread pools, the command will throw error\&. The error will also be triggered
if the newly created worker thread fails to initialize\&.
.TP
\fBtpool::wait\fR \fItpool\fR \fIjoblist\fR ?varname?
This command waits for one or many jobs, whose job IDs are given in the
\fIjoblist\fR to get processed by the worker thread(s)\&. If none of the
specified jobs are ready, the command will enter the event loop, service
events and wait for the first job to get ready\&.
.sp
The command returns the list of completed job IDs\&. If the optional variable
?varname? is given, it will be set to the list of jobs in the
\fIjoblist\fR which are still pending\&. If the threadpool \fItpool\fR
is not found in the list of active thread pools, the command will throw error\&.
.TP
\fBtpool::cancel\fR \fItpool\fR \fIjoblist\fR ?varname?
This command cancels the previously posted jobs given by the \fIjoblist\fR
to the pool \fItpool\fR\&. Job cancellation succeeds only for job still
waiting to be processed\&. If the job is already being executed by one of
the worker threads, the job will not be cancelled\&.
The command returns the list of cancelled job IDs\&. If the optional variable
?varname? is given, it will be set to the list of jobs in the
\fIjoblist\fR which were not cancelled\&. If the threadpool \fItpool\fR
is not found in the list of active thread pools, the command will throw error\&.
.TP
\fBtpool::get\fR \fItpool\fR \fIjob\fR
This command retrieves the result of the previously posted \fIjob\fR\&.
Only results of jobs waited upon with the \fBtpool::wait\fR command
can be retrieved\&. If the execution of the script resulted in error,
the command will throw the error and update the \fBerrorInfo\fR and
\fBerrorCode\fR variables correspondingly\&. If the pool \fItpool\fR
is not found in the list of threadpools, the command will throw error\&.
If the job \fIjob\fR is not ready for retrieval, because it is currently
being executed by the worker thread, the command will throw error\&.
.TP
\fBtpool::preserve\fR \fItpool\fR
Each call to this command increments the reference counter of the
threadpool \fItpool\fR by one (1)\&. Command returns the value of the
reference counter after the increment\&.
By incrementing the reference counter, the caller signalizes that
he/she wishes to use the resource for a longer period of time\&.
.TP
\fBtpool::release\fR \fItpool\fR
Each call to this command decrements the reference counter of the
threadpool \fItpool\fR by one (1)\&.Command returns the value of the
reference counter after the decrement\&.
When the reference counter reaches zero (0), the threadpool \fItpool\fR
is marked for termination\&. You should not reference the threadpool
after the \fBtpool::release\fR command returns zero\&. The \fItpool\fR
handle goes out of scope and should not be used any more\&. Any following
reference to the same threadpool handle will result in Tcl error\&.
.TP
\fBtpool::suspend\fR \fItpool\fR
Suspends processing work on this queue\&. All pool workers are paused
but additional work can be added to the pool\&. Note that adding the
additional work will not increase the number of workers dynamically
as the pool processing is suspended\&. Number of workers is maintained
to the count that was found prior suspending worker activity\&.
If you need to assure certain number of worker threads, use the
\fBminworkers\fR option of the \fBtpool::create\fR command\&.
.TP
\fBtpool::resume\fR \fItpool\fR
Resume processing work on this queue\&. All paused (suspended)
workers are free to get work from the pool\&. Note that resuming pool
operation will just let already created workers to proceed\&.
It will not create additional worker threads to handle the work
posted to the pool's work queue\&.
.PP
.SH DISCUSSION
Threadpool is one of the most common threading paradigm when it comes
to server applications handling a large number of relatively small tasks\&.
A very simplistic model for building a server application would be to
create a new thread each time a request arrives and service the request
in the new thread\&. One of the disadvantages of this approach is that
the overhead of creating a new thread for each request is significant;
a server that created a new thread for each request would spend more time
and consume more system resources in creating and destroying threads than
in processing actual user requests\&. In addition to the overhead of
creating and destroying threads, active threads consume system resources\&.
Creating too many threads can cause the system to run out of memory or
trash due to excessive memory consumption\&.
.PP
A thread pool offers a solution to both the problem of thread life-cycle
overhead and the problem of resource trashing\&. By reusing threads for
multiple tasks, the thread-creation overhead is spread over many tasks\&.
As a bonus, because the thread already exists when a request arrives,
the delay introduced by thread creation is eliminated\&. Thus, the request
can be serviced immediately\&. Furthermore, by properly tuning the number
of threads in the thread pool, resource thrashing may also be eliminated
by forcing any request to wait until a thread is available to process it\&.
.SH "SEE ALSO"
thread, tsv, ttrace
.SH KEYWORDS
thread, threadpool

628
pkgs/thread2.8.7/doc/man/tsv.n Normal file
View File

@@ -0,0 +1,628 @@
'\"
'\" Generated from file '' by tcllib/doctools with format 'nroff'
'\"
.TH "tsv" n 2\&.8 "Tcl Threading"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\" Start paragraph describing an argument to a library procedure.
.\" type is type of argument (int, etc.), in/out is either "in", "out",
.\" or "in/out" to describe whether procedure reads or modifies arg,
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
.\" needed; use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\" Give maximum sizes of arguments for setting tab stops. Type and
.\" name are examples of largest possible arguments that will be passed
.\" to .AP later. If args are omitted, default tab stops are used.
.\"
.\" .BS
.\" Start box enclosure. From here until next .BE, everything will be
.\" enclosed in one large box.
.\"
.\" .BE
.\" End of box enclosure.
.\"
.\" .CS
.\" Begin code excerpt.
.\"
.\" .CE
.\" End code excerpt.
.\"
.\" .VS ?version? ?br?
.\" Begin vertical sidebar, for use in marking newly-changed parts
.\" of man pages. The first argument is ignored and used for recording
.\" the version when the .VS was added, so that the sidebars can be
.\" found and removed when they reach a certain age. If another argument
.\" is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\" End of vertical sidebar.
.\"
.\" .DS
.\" Begin an indented unfilled display.
.\"
.\" .DE
.\" End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\" Start of list of standard options for a Tk widget. The manpage
.\" argument defines where to look up the standard options; if
.\" omitted, defaults to "options". The options follow on successive
.\" lines, in three columns separated by tabs.
.\"
.\" .SE
.\" End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\" Start of description of a specific option. cmdName gives the
.\" option's name as specified in the class command, dbName gives
.\" the option's name in the option database, and dbClass gives
.\" the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\" Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
.\" (for trailing punctuation) and then a closing parenthesis.
.\"
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\" # BS - start boxed text
.\" # ^y = starting y location
.\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\" # VS - start vertical sidebar
.\" # ^Y = starting y location
.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\" # Special macro to handle page bottom: finish off current
.\" # box/sidebar if in box/sidebar mode, then invoked standard
.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
.\" # DE - end display
.de DE
.fi
.RE
.sp
..
.\" # SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\" # CE - end code excerpt
.de CE
.fi
.RE
..
.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\" # QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\" # PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\" # QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\" # MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
tsv \- Part of the Tcl threading extension allowing script level manipulation of data shared between threads\&.
.SH SYNOPSIS
package require \fBTcl 8\&.4\fR
.sp
package require \fBThread ?2\&.8?\fR
.sp
\fBtsv::names\fR ?pattern?
.sp
\fBtsv::object\fR \fIvarname\fR \fIelement\fR
.sp
\fBtsv::set\fR \fIvarname\fR \fIelement\fR ?value?
.sp
\fBtsv::get\fR \fIvarname\fR \fIelement\fR ?namedvar?
.sp
\fBtsv::unset\fR \fIvarname\fR ?element?
.sp
\fBtsv::exists\fR \fIvarname\fR \fIelement\fR
.sp
\fBtsv::pop\fR \fIvarname\fR \fIelement\fR
.sp
\fBtsv::move\fR \fIvarname\fR \fIoldname\fR \fInewname\fR
.sp
\fBtsv::incr\fR \fIvarname\fR \fIelement\fR ?count?
.sp
\fBtsv::append\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value \&.\&.\&.?
.sp
\fBtsv::lock\fR \fIvarname\fR \fIarg\fR ?arg \&.\&.\&.?
.sp
\fBtsv::handlers\fR
.sp
\fBtsv::lappend\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value \&.\&.\&.?
.sp
\fBtsv::linsert\fR \fIvarname\fR \fIelement\fR \fIindex\fR \fIvalue\fR ?value \&.\&.\&.?
.sp
\fBtsv::lreplace\fR \fIvarname\fR \fIelement\fR \fIfirst\fR \fIlast\fR ?value \&.\&.\&.?
.sp
\fBtsv::llength\fR \fIvarname\fR \fIelement\fR
.sp
\fBtsv::lindex\fR \fIvarname\fR \fIelement\fR ?index?
.sp
\fBtsv::lrange\fR \fIvarname\fR \fIelement\fR \fIfrom\fR \fIto\fR
.sp
\fBtsv::lsearch\fR \fIvarname\fR \fIelement\fR ?options? \fIpattern\fR
.sp
\fBtsv::lset\fR \fIvarname\fR \fIelement\fR \fIindex\fR ?index \&.\&.\&.? \fIvalue\fR
.sp
\fBtsv::lpop\fR \fIvarname\fR \fIelement\fR ?index?
.sp
\fBtsv::lpush\fR \fIvarname\fR \fIelement\fR ?index?
.sp
\fBtsv::array set\fR \fIvarname\fR \fIlist\fR
.sp
\fBtsv::array get\fR \fIvarname\fR ?pattern?
.sp
\fBtsv::array names\fR \fIvarname\fR ?pattern?
.sp
\fBtsv::array size\fR \fIvarname\fR
.sp
\fBtsv::array reset\fR \fIvarname\fR \fIlist\fR
.sp
\fBtsv::array bind\fR \fIvarname\fR \fIhandle\fR
.sp
\fBtsv::array unbind\fR \fIvarname\fR
.sp
\fBtsv::array isbound\fR \fIvarname\fR
.sp
\fBtsv::keyldel\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR
.sp
\fBtsv::keylget\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR ?retvar?
.sp
\fBtsv::keylkeys\fR \fIvarname\fR \fIkeylist\fR ?key?
.sp
\fBtsv::keylset\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR \fIvalue\fR ?key value\&.\&.?
.sp
.BE
.SH DESCRIPTION
This section describes commands implementing thread shared variables\&.
A thread shared variable is very similar to a Tcl array but in
contrast to a Tcl array it is created in shared memory and can
be accessed from many threads at the same time\&. Important feature of
thread shared variable is that each access to the variable is internaly
protected by a mutex so script programmer does not have to take care
about locking the variable himself\&.
.PP
Thread shared variables are not bound to any thread explicitly\&. That
means that when a thread which created any of thread shared variables
exits, the variable and associated memory is not unset/reclaimed\&.
User has to explicitly unset the variable to reclaim the memory
consumed by the variable\&.
.SH "ELEMENT COMMANDS"
.TP
\fBtsv::names\fR ?pattern?
Returns names of shared variables matching optional ?pattern?
or all known variables if pattern is ommited\&.
.TP
\fBtsv::object\fR \fIvarname\fR \fIelement\fR
Creates object accessor command for the \fIelement\fR in the
shared variable \fIvarname\fR\&. Using this command, one can apply most
of the other shared variable commands as method functions of
the element object command\&. The object command is automatically
deleted when the element which this command is pointing to is unset\&.
.CS
% tsv::set foo bar "A shared string"
% set string [tsv::object foo bar]
% $string append " appended"
=> A shared string appended
.CE
.TP
\fBtsv::set\fR \fIvarname\fR \fIelement\fR ?value?
Sets the value of the \fIelement\fR in the shared variable \fIvarname\fR
to \fIvalue\fR and returns the value to caller\&. The \fIvalue\fR
may be ommited, in which case the command will return the current
value of the element\&. If the element cannot be found, error is triggered\&.
.TP
\fBtsv::get\fR \fIvarname\fR \fIelement\fR ?namedvar?
Retrieves the value of the \fIelement\fR from the shared variable \fIvarname\fR\&.
If the optional argument \fInamedvar\fR is given, the value is
stored in the named variable\&. Return value of the command depends
of the existence of the optional argument \fInamedvar\fR\&.
If the argument is ommited and the requested element cannot be found
in the shared array, the command triggers error\&. If, however, the
optional argument is given on the command line, the command returns
true (1) if the element is found or false (0) if the element is not found\&.
.TP
\fBtsv::unset\fR \fIvarname\fR ?element?
Unsets the \fIelement\fR from the shared variable \fIvarname\fR\&.
If the optional element is not given, it deletes the variable\&.
.TP
\fBtsv::exists\fR \fIvarname\fR \fIelement\fR
Checks wether the \fIelement\fR exists in the shared variable \fIvarname\fR
and returns true (1) if it does or false (0) if it doesn't\&.
.TP
\fBtsv::pop\fR \fIvarname\fR \fIelement\fR
Returns value of the \fIelement\fR in the shared variable \fIvarname\fR
and unsets the element, all in one atomic operation\&.
.TP
\fBtsv::move\fR \fIvarname\fR \fIoldname\fR \fInewname\fR
Renames the element \fIoldname\fR to the \fInewname\fR in the
shared variable \fIvarname\fR\&. This effectively performs an get/unset/set
sequence of operations but all in one atomic step\&.
.TP
\fBtsv::incr\fR \fIvarname\fR \fIelement\fR ?count?
Similar to standard Tcl \fBincr\fR command but increments the value
of the \fIelement\fR in shared variaboe \fIvarname\fR instead of
the Tcl variable\&.
.TP
\fBtsv::append\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value \&.\&.\&.?
Similar to standard Tcl \fBappend\fR command but appends one or more
values to the \fIelement\fR in shared variable \fIvarname\fR instead of the
Tcl variable\&.
.TP
\fBtsv::lock\fR \fIvarname\fR \fIarg\fR ?arg \&.\&.\&.?
This command concatenates passed arguments and evaluates the
resulting script under the internal mutex protection\&. During the
script evaluation, the entire shared variable is locked\&. For shared
variable commands within the script, internal locking is disabled
so no deadlock can occur\&. It is also allowed to unset the shared
variable from within the script\&. The shared variable is automatically
created if it did not exists at the time of the first lock operation\&.
.CS
% tsv::lock foo {
tsv::lappend foo bar 1
tsv::lappend foo bar 2
puts stderr [tsv::set foo bar]
tsv::unset foo
}
.CE
.TP
\fBtsv::handlers\fR
Returns the names of all persistent storage handlers enabled at compile time\&.
See \fBARRAY COMMANDS\fR for details\&.
.PP
.SH "LIST COMMANDS"
Those command are similar to the equivalently named Tcl command\&. The difference
is that they operate on elements of shared arrays\&.
.TP
\fBtsv::lappend\fR \fIvarname\fR \fIelement\fR \fIvalue\fR ?value \&.\&.\&.?
Similar to standard Tcl \fBlappend\fR command but appends one
or more values to the \fIelement\fR in shared variable \fIvarname\fR
instead of the Tcl variable\&.
.TP
\fBtsv::linsert\fR \fIvarname\fR \fIelement\fR \fIindex\fR \fIvalue\fR ?value \&.\&.\&.?
Similar to standard Tcl \fBlinsert\fR command but inserts one
or more values at the \fIindex\fR list position in the
\fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl variable\&.
.TP
\fBtsv::lreplace\fR \fIvarname\fR \fIelement\fR \fIfirst\fR \fIlast\fR ?value \&.\&.\&.?
Similar to standard Tcl \fBlreplace\fR command but replaces one
or more values between the \fIfirst\fR and \fIlast\fR position
in the \fIelement\fR of the shared variable \fIvarname\fR instead of
the Tcl variable\&.
.TP
\fBtsv::llength\fR \fIvarname\fR \fIelement\fR
Similar to standard Tcl \fBllength\fR command but returns length
of the \fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl
variable\&.
.TP
\fBtsv::lindex\fR \fIvarname\fR \fIelement\fR ?index?
Similar to standard Tcl \fBlindex\fR command but returns the value
at the \fIindex\fR list position of the \fIelement\fR from
the shared variable \fIvarname\fR instead of the Tcl variable\&.
.TP
\fBtsv::lrange\fR \fIvarname\fR \fIelement\fR \fIfrom\fR \fIto\fR
Similar to standard Tcl \fBlrange\fR command but returns values
between \fIfrom\fR and \fIto\fR list positions from the
\fIelement\fR in the shared variable \fIvarname\fR instead of the Tcl variable\&.
.TP
\fBtsv::lsearch\fR \fIvarname\fR \fIelement\fR ?options? \fIpattern\fR
Similar to standard Tcl \fBlsearch\fR command but searches the \fIelement\fR
in the shared variable \fIvarname\fR instead of the Tcl variable\&.
.TP
\fBtsv::lset\fR \fIvarname\fR \fIelement\fR \fIindex\fR ?index \&.\&.\&.? \fIvalue\fR
Similar to standard Tcl \fBlset\fR command but sets the \fIelement\fR
in the shared variable \fIvarname\fR instead of the Tcl variable\&.
.TP
\fBtsv::lpop\fR \fIvarname\fR \fIelement\fR ?index?
Similar to the standard Tcl \fBlindex\fR command but in addition to
returning, it also splices the value out of the \fIelement\fR
from the shared variable \fIvarname\fR in one atomic operation\&.
In contrast to the Tcl \fBlindex\fR command, this command returns
no value to the caller\&.
.TP
\fBtsv::lpush\fR \fIvarname\fR \fIelement\fR ?index?
This command performes the opposite of the \fBtsv::lpop\fR command\&.
As its counterpart, it returns no value to the caller\&.
.PP
.SH "ARRAY COMMANDS"
This command supports most of the options of the standard Tcl
\fBarray\fR command\&. In addition to those, it allows binding
a shared variable to some persisten storage databases\&. Currently the persistent
options supported are the famous GNU Gdbm and LMDB\&. These options have to be
selected during the package compilation time\&.
The implementation provides hooks for defining other persistency layers, if
needed\&.
.TP
\fBtsv::array set\fR \fIvarname\fR \fIlist\fR
Does the same as standard Tcl \fBarray set\fR\&.
.TP
\fBtsv::array get\fR \fIvarname\fR ?pattern?
Does the same as standard Tcl \fBarray get\fR\&.
.TP
\fBtsv::array names\fR \fIvarname\fR ?pattern?
Does the same as standard Tcl \fBarray names\fR\&.
.TP
\fBtsv::array size\fR \fIvarname\fR
Does the same as standard Tcl \fBarray size\fR\&.
.TP
\fBtsv::array reset\fR \fIvarname\fR \fIlist\fR
Does the same as standard Tcl \fBarray set\fR but it clears
the \fIvarname\fR and sets new values from the list atomically\&.
.TP
\fBtsv::array bind\fR \fIvarname\fR \fIhandle\fR
Binds the \fIvarname\fR to the persistent storage \fIhandle\fR\&.
The format of the \fIhandle\fR is <handler>:<address>, where <handler> is
"gdbm" for GNU Gdbm and "lmdb" for LMDB and <address> is the path to the
database file\&.
.TP
\fBtsv::array unbind\fR \fIvarname\fR
Unbinds the shared \fIarray\fR from its bound persistent storage\&.
.TP
\fBtsv::array isbound\fR \fIvarname\fR
Returns true (1) if the shared \fIvarname\fR is bound to some
persistent storage or zero (0) if not\&.
.PP
.SH "KEYED LIST COMMANDS"
Keyed list commands are borrowed from the TclX package\&. Keyed lists provide
a structured data type built upon standard Tcl lists\&. This is a functionality
similar to structs in the C programming language\&.
.PP
A keyed list is a list in which each element contains a key and value
pair\&. These element pairs are stored as lists themselves, where the key
is the first element of the list, and the value is the second\&. The
key-value pairs are referred to as fields\&. This is an example of a
keyed list:
.CS
{{NAME {Frank Zappa}} {JOB {musician and composer}}}
.CE
Fields may contain subfields; `\&.' is the separator character\&. Subfields
are actually fields where the value is another keyed list\&. Thus the
following list has the top level fields ID and NAME, and subfields
NAME\&.FIRST and NAME\&.LAST:
.CS
{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}
.CE
There is no limit to the recursive depth of subfields,
allowing one to build complex data structures\&. Keyed lists are constructed
and accessed via a number of commands\&. All keyed list management
commands take the name of the variable containing the keyed list as an
argument (i\&.e\&. passed by reference), rather than passing the list directly\&.
.TP
\fBtsv::keyldel\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR
Delete the field specified by \fIkey\fR from the keyed list \fIkeylist\fR
in the shared variable \fIvarname\fR\&.
This removes both the key and the value from the keyed list\&.
.TP
\fBtsv::keylget\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR ?retvar?
Return the value associated with \fIkey\fR from the keyed list \fIkeylist\fR
in the shared variable \fIvarname\fR\&.
If the optional \fIretvar\fR is not specified, then the value will be
returned as the result of the command\&. In this case, if key is not found
in the list, an error will result\&.
.sp
If \fIretvar\fR is specified and \fIkey\fR is in the list, then the value
is returned in the variable \fIretvar\fR and the command returns 1 if the
key was present within the list\&. If \fIkey\fR isn't in the list, the
command will return 0, and \fIretvar\fR will be left unchanged\&. If {} is
specified for \fIretvar\fR, the value is not returned, allowing the Tcl
programmer to determine if a \fIkey\fR is present in a keyed list without
setting a variable as a side-effect\&.
.TP
\fBtsv::keylkeys\fR \fIvarname\fR \fIkeylist\fR ?key?
Return the a list of the keys in the keyed list \fIkeylist\fR in the
shared variable \fIvarname\fR\&. If \fIkey\fR is specified, then it is
the name of a key field who's subfield keys are to be retrieved\&.
.TP
\fBtsv::keylset\fR \fIvarname\fR \fIkeylist\fR \fIkey\fR \fIvalue\fR ?key value\&.\&.?
Set the value associated with \fIkey\fR, in the keyed list \fIkeylist\fR
to \fIvalue\fR\&. If the \fIkeylist\fR does not exists, it is created\&.
If \fIkey\fR is not currently in the list, it will be added\&. If it already
exists, \fIvalue\fR replaces the existing value\&. Multiple keywords and
values may be specified, if desired\&.
.PP
.SH DISCUSSION
The current implementation of thread shared variables allows for easy and
convenient access to data shared between different threads\&.
Internally, the data is stored in Tcl objects and all package commands
operate on internal data representation, thus minimizing shimmering and
improving performance\&. Special care has been taken to assure that all
object data is properly locked and deep-copied when moving objects between
threads\&.
.PP
Due to the internal design of the Tcl core, there is no provision of full
integration of shared variables within the Tcl syntax, unfortunately\&. All
access to shared data must be performed with the supplied package commands\&.
Also, variable traces are not supported\&. But even so, benefits of easy,
simple and safe shared data manipulation outweights imposed limitations\&.
.SH CREDITS
Thread shared variables are inspired by the nsv interface found in
AOLserver, a highly scalable Web server from America Online\&.
.SH "SEE ALSO"
thread, tpool, ttrace
.SH KEYWORDS
locking, synchronization, thread shared data, threads

506
pkgs/thread2.8.7/doc/man/ttrace.n Normal file
View File

@@ -0,0 +1,506 @@
'\"
'\" Generated from file '' by tcllib/doctools with format 'nroff'
'\"
.TH "ttrace" n 2\&.8 "Tcl Threading"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\" Start paragraph describing an argument to a library procedure.
.\" type is type of argument (int, etc.), in/out is either "in", "out",
.\" or "in/out" to describe whether procedure reads or modifies arg,
.\" and indent is equivalent to second arg of .IP (shouldn't ever be
.\" needed; use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\" Give maximum sizes of arguments for setting tab stops. Type and
.\" name are examples of largest possible arguments that will be passed
.\" to .AP later. If args are omitted, default tab stops are used.
.\"
.\" .BS
.\" Start box enclosure. From here until next .BE, everything will be
.\" enclosed in one large box.
.\"
.\" .BE
.\" End of box enclosure.
.\"
.\" .CS
.\" Begin code excerpt.
.\"
.\" .CE
.\" End code excerpt.
.\"
.\" .VS ?version? ?br?
.\" Begin vertical sidebar, for use in marking newly-changed parts
.\" of man pages. The first argument is ignored and used for recording
.\" the version when the .VS was added, so that the sidebars can be
.\" found and removed when they reach a certain age. If another argument
.\" is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\" End of vertical sidebar.
.\"
.\" .DS
.\" Begin an indented unfilled display.
.\"
.\" .DE
.\" End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\" Start of list of standard options for a Tk widget. The manpage
.\" argument defines where to look up the standard options; if
.\" omitted, defaults to "options". The options follow on successive
.\" lines, in three columns separated by tabs.
.\"
.\" .SE
.\" End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\" Start of description of a specific option. cmdName gives the
.\" option's name as specified in the class command, dbName gives
.\" the option's name in the option database, and dbClass gives
.\" the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\" Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\" Print an open parenthesis, arg1 in quotes, then arg2 normally
.\" (for trailing punctuation) and then a closing parenthesis.
.\"
.\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\" # Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
. ie !"\\$2"" .TP \\n()Cu
. el .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1 \\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\" # define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\" # BS - start boxed text
.\" # ^y = starting y location
.\" # ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\" # BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\" Draw four-sided box normally, but don't draw top of
.\" box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\" # VS - start vertical sidebar
.\" # ^Y = starting y location
.\" # ^v = 1 (for troff; for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\" # VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\" # Special macro to handle page bottom: finish off current
.\" # box/sidebar if in box/sidebar mode, then invoked standard
.\" # page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\" Draw three-sided box if this is the box's first page,
.\" draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\" # DS - begin display
.de DS
.RS
.nf
.sp
..
.\" # DE - end display
.de DE
.fi
.RE
.sp
..
.\" # SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\" # SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\" # OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name: \\fB\\$1\\fR
Database Name: \\fB\\$2\\fR
Database Class: \\fB\\$3\\fR
.fi
.IP
..
.\" # CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\" # CE - end code excerpt
.de CE
.fi
.RE
..
.\" # UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\" # QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\" # PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\" # QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\" # MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
ttrace \- Trace-based interpreter initialization
.SH SYNOPSIS
package require \fBTcl 8\&.4\fR
.sp
package require \fBThread ?2\&.8?\fR
.sp
\fBttrace::eval\fR \fIarg\fR ?arg \&.\&.\&.?
.sp
\fBttrace::enable\fR
.sp
\fBttrace::disable\fR
.sp
\fBttrace::cleanup\fR
.sp
\fBttrace::update\fR ?epoch?
.sp
\fBttrace::getscript\fR
.sp
\fBttrace::atenable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
.sp
\fBttrace::atdisable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
.sp
\fBttrace::addtrace\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
.sp
\fBttrace::addscript\fR \fIname\fR \fIbody\fR
.sp
\fBttrace::addresolver\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
.sp
\fBttrace::addcleanup\fR \fIbody\fR
.sp
\fBttrace::addentry\fR \fIcmd\fR \fIvar\fR \fIval\fR
.sp
\fBttrace::getentry\fR \fIcmd\fR \fIvar\fR
.sp
\fBttrace::getentries\fR \fIcmd\fR ?pattern?
.sp
\fBttrace::delentry\fR \fIcmd\fR
.sp
\fBttrace::preload\fR \fIcmd\fR
.sp
.BE
.SH DESCRIPTION
This package creates a framework for on-demand replication of the
interpreter state accross threads in an multithreading application\&.
It relies on the mechanics of Tcl command tracing and the Tcl
\fBunknown\fR command and mechanism\&.
.PP
The package requires Tcl threading extension but can be alternatively
used stand-alone within the AOLserver, a scalable webserver from
America Online\&.
.PP
In a nutshell, a short sample illustrating the usage of the ttrace
with the Tcl threading extension:
.CS
% package require Ttrace
2\&.8\&.0
% set t1 [thread::create {package require Ttrace; thread::wait}]
tid0x1802800
% ttrace::eval {proc test args {return test-[thread::id]}}
% thread::send $t1 test
test-tid0x1802800
% set t2 [thread::create {package require Ttrace; thread::wait}]
tid0x1804000
% thread::send $t2 test
test-tid0x1804000
.CE
.PP
As seen from above, the \fBttrace::eval\fR and \fBttrace::update\fR
commands are used to create a thread-wide definition of a simple
Tcl procedure and replicate that definition to all, already existing
or later created, threads\&.
.SH "USER COMMANDS"
This section describes user-level commands\&. Those commands can be
used by script writers to control the execution of the tracing
framework\&.
.TP
\fBttrace::eval\fR \fIarg\fR ?arg \&.\&.\&.?
This command concatenates given arguments and evaluates the resulting
Tcl command with trace framework enabled\&. If the command execution
was ok, it takes necessary steps to automatically propagate the
trace epoch change to all threads in the application\&.
For AOLserver, only newly created threads actually receive the
epoch change\&. For the Tcl threading extension, all threads created by
the extension are automatically updated\&. If the command execution
resulted in Tcl error, no state propagation takes place\&.
.sp
This is the most important user-level command of the package as
it wraps most of the commands described below\&. This greatly
simplifies things, because user need to learn just this (one)
command in order to effectively use the package\&. Other commands,
as desribed below, are included mostly for the sake of completeness\&.
.TP
\fBttrace::enable\fR
Activates all registered callbacks in the framework
and starts a new trace epoch\&. The trace epoch encapsulates all
changes done to the interpreter during the time traces are activated\&.
.TP
\fBttrace::disable\fR
Deactivates all registered callbacks in the framework
and closes the current trace epoch\&.
.TP
\fBttrace::cleanup\fR
Used to clean-up all on-demand loaded resources in the interpreter\&.
It effectively brings Tcl interpreter to its pristine state\&.
.TP
\fBttrace::update\fR ?epoch?
Used to refresh the state of the interpreter to match the optional
trace ?epoch?\&. If the optional ?epoch? is not given, it takes
the most recent trace epoch\&.
.TP
\fBttrace::getscript\fR
Returns a synthetized Tcl script which may be sourced in any interpreter\&.
This script sets the stage for the Tcl \fBunknown\fR command so it can
load traced resources from the in-memory database\&. Normally, this command
is automatically invoked by other higher-level commands like
\fBttrace::eval\fR and \fBttrace::update\fR\&.
.PP
.SH "CALLBACK COMMANDS"
A word upfront: the package already includes callbacks for tracing
following Tcl commands: \fBproc\fR, \fBnamespace\fR, \fBvariable\fR,
\fBload\fR, and \fBrename\fR\&. Additionaly, a set of callbacks for
tracing resources (object, clasess) for the XOTcl v1\&.3\&.8+, an
OO-extension to Tcl, is also provided\&.
This gives a solid base for solving most of the real-life needs and
serves as an example for people wanting to customize the package
to cover their specific needs\&.
.PP
Below, you can find commands for registering callbacks in the
framework and for writing callback scripts\&. These callbacks are
invoked by the framework in order to gather interpreter state
changes, build in-memory database, perform custom-cleanups and
various other tasks\&.
.TP
\fBttrace::atenable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
Registers Tcl callback to be activated at \fBttrace::enable\fR\&.
Registered callbacks are activated on FIFO basis\&. The callback
definition includes the name of the callback, \fIcmd\fR, a list
of callback arguments, \fIarglist\fR and the \fIbody\fR of the
callback\&. Effectively, this actually resembles the call interface
of the standard Tcl \fBproc\fR command\&.
.TP
\fBttrace::atdisable\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
Registers Tcl callback to be activated at \fBttrace::disable\fR\&.
Registered callbacks are activated on FIFO basis\&. The callback
definition includes the name of the callback, \fIcmd\fR, a list
of callback arguments, \fIarglist\fR and the \fIbody\fR of the
callback\&. Effectively, this actually resembles the call interface
of the standard Tcl \fBproc\fR command\&.
.TP
\fBttrace::addtrace\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
Registers Tcl callback to be activated for tracing the Tcl
\fBcmd\fR command\&. The callback definition includes the name of
the Tcl command to trace, \fIcmd\fR, a list of callback arguments,
\fIarglist\fR and the \fIbody\fR of the callback\&. Effectively,
this actually resembles the call interface of the standard Tcl
\fBproc\fR command\&.
.TP
\fBttrace::addscript\fR \fIname\fR \fIbody\fR
Registers Tcl callback to be activated for building a Tcl
script to be passed to other interpreters\&. This script is
used to set the stage for the Tcl \fBunknown\fR command\&.
Registered callbacks are activated on FIFO basis\&.
The callback definition includes the name of the callback,
\fIname\fR and the \fIbody\fR of the callback\&.
.TP
\fBttrace::addresolver\fR \fIcmd\fR \fIarglist\fR \fIbody\fR
Registers Tcl callback to be activated by the overloaded Tcl
\fBunknown\fR command\&.
Registered callbacks are activated on FIFO basis\&.
This callback is used to resolve the resource and load the
resource in the current interpreter\&.
.TP
\fBttrace::addcleanup\fR \fIbody\fR
Registers Tcl callback to be activated by the \fBtrace::cleanup\fR\&.
Registered callbacks are activated on FIFO basis\&.
.TP
\fBttrace::addentry\fR \fIcmd\fR \fIvar\fR \fIval\fR
Adds one entry to the named in-memory database\&.
.TP
\fBttrace::getentry\fR \fIcmd\fR \fIvar\fR
Returns the value of the entry from the named in-memory database\&.
.TP
\fBttrace::getentries\fR \fIcmd\fR ?pattern?
Returns names of all entries from the named in-memory database\&.
.TP
\fBttrace::delentry\fR \fIcmd\fR
Deletes an entry from the named in-memory database\&.
.TP
\fBttrace::preload\fR \fIcmd\fR
Registers the Tcl command to be loaded in the interpreter\&.
Commands registered this way will always be the part of
the interpreter and not be on-demand loaded by the Tcl
\fBunknown\fR command\&.
.PP
.SH DISCUSSION
Common introspective state-replication approaches use a custom Tcl
script to introspect the running interpreter and synthesize another
Tcl script to replicate this state in some other interpreter\&.
This package, on the contrary, uses Tcl command traces\&. Command
traces are registered on selected Tcl commands, like \fBproc\fR,
\fBnamespace\fR, \fBload\fR and other standard (and/or user-defined)
Tcl commands\&. When activated, those traces build an in-memory
database of created resources\&. This database is used as a resource
repository for the (overloaded) Tcl \fBunknown\fR command which
creates the requested resource in the interpreter on demand\&.
This way, users can update just one interpreter (master) in one
thread and replicate that interpreter state (or part of it) to other
threads/interpreters in the process\&.
.PP
Immediate benefit of such approach is the much smaller memory footprint
of the application and much faster thread creation\&. By not actually
loading all necessary procedures (and other resources) in every thread
at the thread initialization time, but by deffering this to the time the
resource is actually referenced, significant improvements in both
memory consumption and thread initialization time can be achieved\&. Some
tests have shown that memory footprint of an multithreading Tcl application
went down more than three times and thread startup time was reduced for
about 50 times\&. Note that your mileage may vary\&.
Other benefits include much finer control about what (and when) gets
replicated from the master to other Tcl thread/interpreters\&.
.SH "SEE ALSO"
thread, tpool, tsv
.SH KEYWORDS
command tracing, introspection