home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tcl2-73c.zip / tcl7.3 / doc / Async.3 < prev    next >
Text File  |  1993-09-17  |  7KB  |  173 lines

  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/Async.3,v 1.5 93/09/17 15:21:50 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tcl_AsyncCreate tclc 7.0
  25. .BS
  26. .SH NAME
  27. Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tcl.h>\fR
  31. .sp
  32. extern int \fBtcl_AsyncReady\fR;
  33. .sp
  34. Tcl_AsyncHandler
  35. \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
  36. .sp
  37. \fBTcl_AsyncMark\fR(\fIasync\fR)
  38. .sp
  39. int
  40. \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
  41. .sp
  42. \fBTcl_AsyncDelete\fR(\fIasync\fR)
  43. .SH ARGUMENTS
  44. .AS Tcl_AsyncHandler clientData
  45. .AP Tcl_AsyncProc *proc in
  46. Procedure to invoke to handle an asynchronous event.
  47. .AP ClientData clientData in
  48. One-word value to pass to \fIproc\fR.
  49. .AP Tcl_AsyncHandler async in
  50. Token for asynchronous event handler.
  51. .AP Tcl_Interp *interp in
  52. Tcl interpreter in which command was being evaluated when handler was
  53. invoked, or NULL if handler was invoked when there was no interpreter
  54. active.
  55. .AP int code in
  56. Completion code from command that just completed in \fIinterp\fR,
  57. or 0 if \fIinterp\fR is NULL.
  58. .BE
  59.  
  60. .SH DESCRIPTION
  61. .PP
  62. These procedures provide a safe mechanism for dealing with
  63. asynchronous events such as signals.
  64. If an event such as a signal occurs while a Tcl script is being
  65. evaluated then it isn't safe to take any substantive action to
  66. process the event.
  67. For example, it isn't safe to evaluate a Tcl script since the
  68. intepreter may already be in the middle of evaluating a script;
  69. it may not even be safe to allocate memory, since a memory
  70. allocation could have been in progress when the event occurred.
  71. The only safe approach is to set a flag indicating that the event
  72. occurred, then handle the event later when the world has returned
  73. to a clean state, such as after the current Tcl command completes.
  74. .PP
  75. \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
  76. a token for it.
  77. The asynchronous handler must be created before
  78. any occurrences of the asynchronous event that it is intended
  79. to handle (it is not safe to create a handler at the time of
  80. an event).
  81. When an asynchronous event occurs the code that detects the event
  82. (such as a signal handler) should call \fBTcl_AsyncMark\fR with the
  83. token for the handler.
  84. \fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
  85. will not invoke the handler immediately.
  86. Tcl will call the \fIproc\fR associated with the handler later, when
  87. the world is in a safe state, and \fIproc\fR can then carry out
  88. the actions associated with the asynchronous event.
  89. \fIProc\fR should have arguments and result that match the
  90. type \fBTcl_AsyncProc\fR:
  91. .nf
  92. .RS
  93. typedef int Tcl_AsyncProc(
  94. .RS
  95. ClientData \fIclientData\fR,
  96. Tcl_Interp *\fIinterp\fR,
  97. int \fIcode\fR);
  98. .RE
  99. .RE
  100. .fi
  101. The \fIclientData\fR will be the same as the \fIclientData\fR
  102. argument passed to \fBTcl_AsyncCreate\fR when the handler was
  103. created.
  104. If \fIproc\fR is invoked just after a command has completed
  105. execution in an interpreter, then \fIinterp\fR will identify
  106. the interpreter in which the command was evaluated and
  107. \fIcode\fR will be the completion code returned by that
  108. command.
  109. The command's result will be present in \fIinterp->result\fR.
  110. When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR
  111. will be returned as the result of the command and the integer
  112. value returned by \fIproc\fR will be used as the new completion
  113. code for the command.
  114. .PP
  115. It is also possible for \fIproc\fR to be invoked when no interpreter
  116. is active.
  117. This can happen, for example, if an asynchronous event occurs while
  118. the application is waiting for interactive input or an X event.
  119. In this case \fIinterp\fR will be NULL and \fIcode\fR will be
  120. 0, and the return value from \fIproc\fR will be ignored.
  121. .PP
  122. The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
  123. handlers that are ready.
  124. The global variable \fBtcl_AsyncReady\fR will be non-zero whenever any
  125. asynchronous handlers are ready;  it can be checked to avoid calls
  126. to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
  127. Tcl checks \fBtcl_AsyncReady\fR after each command is evaluated
  128. and calls \fBTcl_AsyncInvoke\fR if needed.
  129. Applications may also call \fBTcl_AsyncInvoke\fR at interesting
  130. times for that application.
  131. For example, Tk's event handler checks \fBtcl_AsyncReady\fR
  132. after each event and calls \fBTcl_AsyncInvoke\fR if needed.
  133. The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
  134. have the same meaning as for \fIproc\fR:  they identify the active
  135. intepreter, if any, and the completion code from the command
  136. that just completed.
  137. .PP
  138. \fBTcl_AsyncDelete\fR removes an asynchronous handler so that
  139. its \fIproc\fR will never be invoked again.
  140. A handler can be deleted even when ready, and it will still
  141. not be invoked.
  142. .PP
  143. If multiple handlers become active at the same time, the
  144. handlers are invoked in the order they were created (oldest
  145. handler first).
  146. The \fIcode\fR and \fIinterp->result\fR for later handlers
  147. reflect the values returned by earlier handlers, so that
  148. the most recently created handler has last say about
  149. the interpreter's result and completion code.
  150. If new handlers become ready while handlers are executing,
  151. \fBTcl_AsyncInvoke\fR will invoke them all;  at each point it
  152. invokes the highest-priority (oldest) ready handler, repeating
  153. this over and over until there are no longer any ready handlers.
  154.  
  155. .SH WARNING
  156. .PP
  157. It is almost always a bad idea for an asynchronous event
  158. handler to modify \fIinterp->result\fR or return a code different
  159. from its \fIcode\fR argument.
  160. This sort of behavior can disrupt the execution of scripts in
  161. subtle ways and result in bugs that are extremely difficult
  162. to track down.
  163. If an asynchronous event handler needs to evaluate Tcl scripts
  164. then it should first save \fIinterp->result\fR plus the values
  165. of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
  166. be done, for example, by storing them in dynamic strings).
  167. When the asynchronous handler is finished it should restore
  168. \fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR,
  169. and return the \fIcode\fR argument.
  170.  
  171. .SH KEYWORDS
  172. asynchronous event, handler, signal
  173.