Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Doc improvements, backported from trunk. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | thread-2-8-branch |
Files: | files | file ages | folders |
SHA3-256: |
d3520adc0ef778a37f7be7f88ed902f8 |
User & Date: | jan.nijtmans 2019-05-17 12:27:38.987 |
Context
2019-06-29
| ||
14:38 | Use Tcl's built-in Tcl_GetIntForIndex() function (TIP #544) in stead of Thread's own built-in SvGetIntForIndex(). When running on Tcl <= 8.6, use TclGetIntForIndex() in stead (runtime switched) check-in: 91cf470a77 user: jan.nijtmans tags: thread-2-8-branch | |
2019-05-17
| ||
12:28 | Merge thread-2.8-branch check-in: b5278091b6 user: jan.nijtmans tags: trunk | |
12:27 | Doc improvements, backported from trunk. check-in: d3520adc0e user: jan.nijtmans tags: thread-2-8-branch | |
12:19 | Don't thrust availability of Tcl_GetUnicodeFromObj(): If it's not there, just don't use it. check-in: 72ee9d48e5 user: jan.nijtmans tags: thread-2-8-branch | |
2019-05-09
| ||
16:20 | small amend check-in: 6eef222a2f user: sebres tags: trunk | |
Changes
Changes to doc/man/thread.n.
︙ | ︙ | |||
348 349 350 351 352 353 354 | \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\&. | | | > | > | 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 | \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 |
︙ | ︙ | |||
386 387 388 389 390 391 392 | 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 | | | 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 | 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 |
︙ | ︙ | |||
419 420 421 422 423 424 425 | 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 | | | 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 | 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 |
︙ | ︙ | |||
501 502 503 504 505 506 507 | 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 | | | | | | 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 | 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\&. |
︙ | ︙ | |||
548 549 550 551 552 553 554 | 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, | | | 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 | 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] |
︙ | ︙ | |||
623 624 625 626 627 628 629 | .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 | | | | | < < < | | < < | | 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 | .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\&. |
︙ | ︙ | |||
683 684 685 686 687 688 689 | 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 | | | 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 | 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\&. |
︙ | ︙ | |||
735 736 737 738 739 740 741 | .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, | | | 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 | .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 |
︙ | ︙ | |||
779 780 781 782 783 784 785 | .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 | | | | 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 | .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\&. |
︙ | ︙ |