1 | '\" |
---|
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: Async.3,v 1.12 2007/12/13 15:22:30 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | Tcl_AsyncHandler |
---|
20 | \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR) |
---|
21 | .sp |
---|
22 | \fBTcl_AsyncMark\fR(\fIasync\fR) |
---|
23 | .sp |
---|
24 | int |
---|
25 | \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR) |
---|
26 | .sp |
---|
27 | \fBTcl_AsyncDelete\fR(\fIasync\fR) |
---|
28 | .sp |
---|
29 | int |
---|
30 | \fBTcl_AsyncReady\fR() |
---|
31 | .SH ARGUMENTS |
---|
32 | .AS Tcl_AsyncHandler clientData |
---|
33 | .AP Tcl_AsyncProc *proc in |
---|
34 | Procedure to invoke to handle an asynchronous event. |
---|
35 | .AP ClientData clientData in |
---|
36 | One-word value to pass to \fIproc\fR. |
---|
37 | .AP Tcl_AsyncHandler async in |
---|
38 | Token for asynchronous event handler. |
---|
39 | .AP Tcl_Interp *interp in |
---|
40 | Tcl interpreter in which command was being evaluated when handler was |
---|
41 | invoked, or NULL if handler was invoked when there was no interpreter |
---|
42 | active. |
---|
43 | .AP int code in |
---|
44 | Completion code from command that just completed in \fIinterp\fR, |
---|
45 | or 0 if \fIinterp\fR is NULL. |
---|
46 | .BE |
---|
47 | |
---|
48 | .SH DESCRIPTION |
---|
49 | .PP |
---|
50 | These procedures provide a safe mechanism for dealing with |
---|
51 | asynchronous events such as signals. |
---|
52 | If an event such as a signal occurs while a Tcl script is being |
---|
53 | evaluated then it is not safe to take any substantive action to |
---|
54 | process the event. |
---|
55 | For example, it is not safe to evaluate a Tcl script since the |
---|
56 | interpreter may already be in the middle of evaluating a script; |
---|
57 | it may not even be safe to allocate memory, since a memory |
---|
58 | allocation could have been in progress when the event occurred. |
---|
59 | The only safe approach is to set a flag indicating that the event |
---|
60 | occurred, then handle the event later when the world has returned |
---|
61 | to a clean state, such as after the current Tcl command completes. |
---|
62 | .PP |
---|
63 | \fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR |
---|
64 | are thread sensitive. They access and/or set a thread-specific data |
---|
65 | structure in the event of a core built with \fI\-\-enable\-threads\fR. The token |
---|
66 | created by \fBTcl_AsyncCreate\fR contains the needed thread information it |
---|
67 | was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield |
---|
68 | the origin thread into the asynchronous handler. |
---|
69 | .PP |
---|
70 | \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns |
---|
71 | a token for it. |
---|
72 | The asynchronous handler must be created before |
---|
73 | any occurrences of the asynchronous event that it is intended |
---|
74 | to handle (it is not safe to create a handler at the time of |
---|
75 | an event). |
---|
76 | When an asynchronous event occurs the code that detects the event |
---|
77 | (such as a signal handler) should call \fBTcl_AsyncMark\fR with the |
---|
78 | token for the handler. |
---|
79 | \fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it |
---|
80 | will not invoke the handler immediately. |
---|
81 | Tcl will call the \fIproc\fR associated with the handler later, when |
---|
82 | the world is in a safe state, and \fIproc\fR can then carry out |
---|
83 | the actions associated with the asynchronous event. |
---|
84 | \fIProc\fR should have arguments and result that match the |
---|
85 | type \fBTcl_AsyncProc\fR: |
---|
86 | .CS |
---|
87 | typedef int Tcl_AsyncProc( |
---|
88 | ClientData \fIclientData\fR, |
---|
89 | Tcl_Interp *\fIinterp\fR, |
---|
90 | int \fIcode\fR); |
---|
91 | .CE |
---|
92 | The \fIclientData\fR will be the same as the \fIclientData\fR |
---|
93 | argument passed to \fBTcl_AsyncCreate\fR when the handler was |
---|
94 | created. |
---|
95 | If \fIproc\fR is invoked just after a command has completed |
---|
96 | execution in an interpreter, then \fIinterp\fR will identify |
---|
97 | the interpreter in which the command was evaluated and |
---|
98 | \fIcode\fR will be the completion code returned by that |
---|
99 | command. |
---|
100 | The command's result will be present in the interpreter's result. |
---|
101 | When \fIproc\fR returns, whatever it leaves in the interpreter's result |
---|
102 | will be returned as the result of the command and the integer |
---|
103 | value returned by \fIproc\fR will be used as the new completion |
---|
104 | code for the command. |
---|
105 | .PP |
---|
106 | It is also possible for \fIproc\fR to be invoked when no interpreter |
---|
107 | is active. |
---|
108 | This can happen, for example, if an asynchronous event occurs while |
---|
109 | the application is waiting for interactive input or an X event. |
---|
110 | In this case \fIinterp\fR will be NULL and \fIcode\fR will be |
---|
111 | 0, and the return value from \fIproc\fR will be ignored. |
---|
112 | .PP |
---|
113 | The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the |
---|
114 | handlers that are ready. |
---|
115 | The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any |
---|
116 | asynchronous handlers are ready; it can be checked to avoid calls |
---|
117 | to \fBTcl_AsyncInvoke\fR when there are no ready handlers. |
---|
118 | Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated |
---|
119 | and calls \fBTcl_AsyncInvoke\fR if needed. |
---|
120 | Applications may also call \fBTcl_AsyncInvoke\fR at interesting |
---|
121 | times for that application. |
---|
122 | For example, Tcl's event handler calls \fBTcl_AsyncReady\fR |
---|
123 | after each event and calls \fBTcl_AsyncInvoke\fR if needed. |
---|
124 | The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR |
---|
125 | have the same meaning as for \fIproc\fR: they identify the active |
---|
126 | interpreter, if any, and the completion code from the command |
---|
127 | that just completed. |
---|
128 | .PP |
---|
129 | \fBTcl_AsyncDelete\fR removes an asynchronous handler so that |
---|
130 | its \fIproc\fR will never be invoked again. |
---|
131 | A handler can be deleted even when ready, and it will still |
---|
132 | not be invoked. |
---|
133 | .PP |
---|
134 | If multiple handlers become active at the same time, the |
---|
135 | handlers are invoked in the order they were created (oldest |
---|
136 | handler first). |
---|
137 | The \fIcode\fR and the interpreter's result for later handlers |
---|
138 | reflect the values returned by earlier handlers, so that |
---|
139 | the most recently created handler has last say about |
---|
140 | the interpreter's result and completion code. |
---|
141 | If new handlers become ready while handlers are executing, |
---|
142 | \fBTcl_AsyncInvoke\fR will invoke them all; at each point it |
---|
143 | invokes the highest-priority (oldest) ready handler, repeating |
---|
144 | this over and over until there are no longer any ready handlers. |
---|
145 | .SH WARNING |
---|
146 | .PP |
---|
147 | It is almost always a bad idea for an asynchronous event |
---|
148 | handler to modify the interpreter's result or return a code different |
---|
149 | from its \fIcode\fR argument. |
---|
150 | This sort of behavior can disrupt the execution of scripts in |
---|
151 | subtle ways and result in bugs that are extremely difficult |
---|
152 | to track down. |
---|
153 | If an asynchronous event handler needs to evaluate Tcl scripts |
---|
154 | then it should first save the interpreter's state by calling |
---|
155 | \fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument. |
---|
156 | When the asynchronous handler is finished it should restore |
---|
157 | the interpreter's state by calling \fBTcl_RestoreInterpState\fR, |
---|
158 | and then returning the \fIcode\fR argument. |
---|
159 | |
---|
160 | .SH KEYWORDS |
---|
161 | asynchronous event, handler, signal, Tcl_SaveInterpState, thread |
---|