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
82              typedef int Tcl_AsyncProc(
83                      ClientData clientData,
84                      Tcl_Interp *interp,
85                      int code);
86
87       The  clientData  will  be the same as the clientData argument passed to
88       Tcl_AsyncCreate when the handler was created.  If proc is invoked  just
89       after  a command has completed execution in an interpreter, then interp
90       will identify the interpreter in which the command  was  evaluated  and
91       code  will  be  the completion code returned by that command.  The com‐
92       mand's result will be present in the interpreter's result.   When  proc
93       returns,  whatever  it  leaves  in  the  interpreter's  result  will be
94       returned as the result of the command and the integer value returned by
95       proc will be used as the new completion code for the command.
96
97       It  is  also  possible  for  proc  to be invoked when no interpreter is
98       active.  This can happen, for example, if an asynchronous event  occurs
99       while  the  application is waiting for interactive input or an X event.
100       In this case interp will be NULL and code will be  0,  and  the  return
101       value from proc will be ignored.
102
103       The  procedure  Tcl_AsyncInvoke is called to invoke all of the handlers
104       that are ready.  The  procedure  Tcl_AsyncReady  will  return  non-zero
105       whenever  any  asynchronous  handlers  are ready;  it can be checked to
106       avoid calls to Tcl_AsyncInvoke when there are no ready  handlers.   Tcl
107       calls   Tcl_AsyncReady  after  each  command  is  evaluated  and  calls
108       Tcl_AsyncInvoke if needed.  Applications may also call  Tcl_AsyncInvoke
109       at  interesting  times  for that application.  For example, Tcl's event
110       handler calls Tcl_AsyncReady after each event and calls Tcl_AsyncInvoke
111       if  needed.   The interp and code arguments to Tcl_AsyncInvoke have the
112       same meaning as for proc:  they identify  the  active  interpreter,  if
113       any, and the completion code from the command that just completed.
114
115       Tcl_AsyncDelete  removes  an asynchronous handler so that its proc will
116       never be invoked again.  A handler can be deleted even when ready,  and
117       it will still not be invoked.
118
119       If  multiple  handlers become active at the same time, the handlers are
120       invoked in the order they were created  (oldest  handler  first).   The
121       code and the interpreter's result for later handlers reflect the values
122       returned by earlier handlers, so that the most recently created handler
123       has  last  say  about the interpreter's result and completion code.  If
124       new handlers become ready while handlers are executing, Tcl_AsyncInvoke
125       will  invoke  them  all;  at each point it invokes the highest-priority
126       (oldest) ready handler, repeating this over and over until there are no
127       longer any ready handlers.
128

WARNING

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

KEYWORDS

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