1Tcl_AsyncCreate(3)          Tcl Library Procedures          Tcl_AsyncCreate(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_AsyncCreate,   Tcl_AsyncMark,   Tcl_AsyncInvoke,   Tcl_AsyncDelete,
9       Tcl_AsyncReady - handle asynchronous events
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_AsyncHandler
15       Tcl_AsyncCreate(proc, clientData)
16
17       Tcl_AsyncMark(async)
18
19       int
20       Tcl_AsyncInvoke(interp, code)
21
22       Tcl_AsyncDelete(async)
23
24       int
25       Tcl_AsyncReady()
26

ARGUMENTS

28       Tcl_AsyncProc *proc (in)                  Procedure to invoke to handle
29                                                 an asynchronous event.
30
31       ClientData clientData (in)                One-word  value  to  pass  to
32                                                 proc.
33
34       Tcl_AsyncHandler async (in)               Token for asynchronous  event
35                                                 handler.
36
37       Tcl_Interp *interp (in)                   Tcl interpreter in which com‐
38                                                 mand was being evaluated when
39                                                 handler  was invoked, or NULL
40                                                 if handler was  invoked  when
41                                                 there   was   no  interpreter
42                                                 active.
43
44       int code (in)                             Completion code from  command
45                                                 that    just   completed   in
46                                                 interp, or  0  if  interp  is
47                                                 NULL.
48_________________________________________________________________
49
50

DESCRIPTION

52       These procedures provide a safe mechanism for dealing with asynchronous
53       events such as signals.  If an event such as a signal  occurs  while  a
54       Tcl  script is being evaluated then it is not safe to take any substan‐
55       tive action to process the event.  For example, it is not safe to eval‐
56       uate a Tcl script since the interpreter may already be in the middle of
57       evaluating a script; it may not even be safe to allocate memory,  since
58       a  memory  allocation  could  have  been  in  progress  when  the event
59       occurred.  The only safe approach is to set a flag indicating that  the
60       event 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
63       Tcl_AsyncCreate, Tcl_AsyncDelete, and Tcl_AsyncReady are thread  sensi‐
64       tive.   They  access and/or set a thread-specific data structure in the
65       event of a core built with  --enable-threads.   The  token  created  by
66       Tcl_AsyncCreate  contains  the  needed thread information it was called
67       from so that calling Tcl_AsyncMark(token) will only  yield  the  origin
68       thread into the asynchronous handler.
69
70       Tcl_AsyncCreate creates an asynchronous handler and returns a token for
71       it.  The asynchronous handler must be created before any occurrences of
72       the asynchronous event that it is intended to handle (it is not safe to
73       create a handler at the time of an event).  When an asynchronous  event
74       occurs  the  code  that  detects  the  event (such as a signal handler)
75       should call Tcl_AsyncMark with the token for the  handler.   Tcl_Async‐
76       Mark  will mark the handler as ready to execute, but it will not invoke
77       the handler immediately.  Tcl will call the proc  associated  with  the
78       handler  later,  when  the  world is in a safe state, and proc can then
79       carry out the actions associated with  the  asynchronous  event.   Proc
80       should have arguments and result that match the type Tcl_AsyncProc:
81              typedef int Tcl_AsyncProc(
82                      ClientData clientData,
83                      Tcl_Interp *interp,
84                      int code);
85       The  clientData  will  be the same as the clientData argument passed to
86       Tcl_AsyncCreate when the handler was created.  If proc is invoked  just
87       after  a command has completed execution in an interpreter, then interp
88       will identify the interpreter in which the command  was  evaluated  and
89       code  will  be  the completion code returned by that command.  The com‐
90       mand's result will be present in the interpreter's result.   When  proc
91       returns,  whatever  it  leaves  in  the  interpreter's  result  will be
92       returned as the result of the command and the integer value returned by
93       proc will be used as the new completion code for the command.
94
95       It  is  also  possible  for  proc  to be invoked when no interpreter is
96       active.  This can happen, for example, if an asynchronous event  occurs
97       while  the  application is waiting for interactive input or an X event.
98       In this case interp will be NULL and code will be  0,  and  the  return
99       value from proc will be ignored.
100
101       The  procedure  Tcl_AsyncInvoke is called to invoke all of the handlers
102       that are ready.  The  procedure  Tcl_AsyncReady  will  return  non-zero
103       whenever  any  asynchronous  handlers  are ready;  it can be checked to
104       avoid calls to Tcl_AsyncInvoke when there are no ready  handlers.   Tcl
105       calls   Tcl_AsyncReady  after  each  command  is  evaluated  and  calls
106       Tcl_AsyncInvoke if needed.  Applications may also call  Tcl_AsyncInvoke
107       at  interesting  times  for that application.  For example, Tcl's event
108       handler calls Tcl_AsyncReady after each event and calls Tcl_AsyncInvoke
109       if  needed.   The interp and code arguments to Tcl_AsyncInvoke have the
110       same meaning as for proc:  they identify  the  active  interpreter,  if
111       any, and the completion code from the command that just completed.
112
113       Tcl_AsyncDelete  removes  an asynchronous handler so that its proc will
114       never be invoked again.  A handler can be deleted even when ready,  and
115       it will still not be invoked.
116
117       If  multiple  handlers become active at the same time, the handlers are
118       invoked in the order they were created  (oldest  handler  first).   The
119       code and the interpreter's result for later handlers reflect the values
120       returned by earlier handlers, so that the most recently created handler
121       has  last  say  about the interpreter's result and completion code.  If
122       new handlers become ready while handlers are executing, Tcl_AsyncInvoke
123       will  invoke  them  all;  at each point it invokes the highest-priority
124       (oldest) ready handler, repeating this over and over until there are no
125       longer any ready handlers.
126

WARNING

128       It  is  almost  always  a bad idea for an asynchronous event handler to
129       modify the interpreter's result or return a  code  different  from  its
130       code  argument.   This  sort  of  behavior can disrupt the execution of
131       scripts in subtle ways and result in bugs that are extremely  difficult
132       to  track down.  If an asynchronous event handler needs to evaluate Tcl
133       scripts then it should first save the interpreter's  state  by  calling
134       Tcl_SaveInterpState,  passing in the code argument.  When the asynchro‐
135       nous handler is finished it should restore the interpreter's  state  by
136       calling Tcl_RestoreInterpState, and then returning the code argument.
137
138

KEYWORDS

140       asynchronous event, handler, signal, Tcl_SaveInterpState, thread
141
142
143
144Tcl                                   7.0                   Tcl_AsyncCreate(3)
Impressum