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 |
---|