[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1995-1996 Sun Microsystems, Inc. |
---|
| 3 | '\" |
---|
| 4 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 5 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 6 | '\" |
---|
| 7 | '\" RCS: @(#) $Id: vwait.n,v 1.7 2008/01/09 08:09:56 georgeps Exp $ |
---|
| 8 | '\" |
---|
| 9 | .so man.macros |
---|
| 10 | .TH vwait n 8.0 Tcl "Tcl Built-In Commands" |
---|
| 11 | .BS |
---|
| 12 | '\" Note: do not modify the .SH NAME line immediately below! |
---|
| 13 | .SH NAME |
---|
| 14 | vwait \- Process events until a variable is written |
---|
| 15 | .SH SYNOPSIS |
---|
| 16 | \fBvwait\fR \fIvarName\fR |
---|
| 17 | .BE |
---|
| 18 | |
---|
| 19 | .SH DESCRIPTION |
---|
| 20 | .PP |
---|
| 21 | This command enters the Tcl event loop to process events, blocking |
---|
| 22 | the application if no events are ready. It continues processing |
---|
| 23 | events until some event handler sets the value of variable |
---|
| 24 | \fIvarName\fR. Once \fIvarName\fR has been set, the \fBvwait\fR |
---|
| 25 | command will return as soon as the event handler that modified |
---|
| 26 | \fIvarName\fR completes. \fIvarName\fR must be globally scoped |
---|
| 27 | (either with a call to \fBglobal\fR for the \fIvarName\fR, or with |
---|
| 28 | the full namespace path specification). |
---|
| 29 | .PP |
---|
| 30 | In some cases the \fBvwait\fR command may not return immediately |
---|
| 31 | after \fIvarName\fR is set. This can happen if the event handler |
---|
| 32 | that sets \fIvarName\fR does not complete immediately. For example, |
---|
| 33 | if an event handler sets \fIvarName\fR and then itself calls |
---|
| 34 | \fBvwait\fR to wait for a different variable, then it may not return |
---|
| 35 | for a long time. During this time the top-level \fBvwait\fR is |
---|
| 36 | blocked waiting for the event handler to complete, so it cannot |
---|
| 37 | return either. |
---|
| 38 | .SH EXAMPLES |
---|
| 39 | Run the event-loop continually until some event calls \fBexit\fR. |
---|
| 40 | (You can use any variable not mentioned elsewhere, but the name |
---|
| 41 | \fIforever\fR reminds you at a glance of the intent.) |
---|
| 42 | .CS |
---|
| 43 | \fBvwait\fR forever |
---|
| 44 | .CE |
---|
| 45 | .PP |
---|
| 46 | Wait five seconds for a connection to a server socket, otherwise |
---|
| 47 | close the socket and continue running the script: |
---|
| 48 | .CS |
---|
| 49 | # Initialise the state |
---|
| 50 | after 5000 set state timeout |
---|
| 51 | set server [socket -server accept 12345] |
---|
| 52 | proc accept {args} { |
---|
| 53 | global state connectionInfo |
---|
| 54 | set state accepted |
---|
| 55 | set connectionInfo $args |
---|
| 56 | } |
---|
| 57 | |
---|
| 58 | # Wait for something to happen |
---|
| 59 | \fBvwait\fR state |
---|
| 60 | |
---|
| 61 | # Clean up events that could have happened |
---|
| 62 | close $server |
---|
| 63 | after cancel set state timeout |
---|
| 64 | |
---|
| 65 | # Do something based on how the vwait finished... |
---|
| 66 | switch $state { |
---|
| 67 | timeout { |
---|
| 68 | puts "no connection on port 12345" |
---|
| 69 | } |
---|
| 70 | accepted { |
---|
| 71 | puts "connection: $connectionInfo" |
---|
| 72 | puts [lindex $connectionInfo 0] "Hello there!" |
---|
| 73 | } |
---|
| 74 | } |
---|
| 75 | .CE |
---|
| 76 | |
---|
| 77 | .SH "SEE ALSO" |
---|
| 78 | global(n), update(n) |
---|
| 79 | |
---|
| 80 | .SH KEYWORDS |
---|
| 81 | event, variable, wait |
---|