NAME

       Tcl_AsyncCreate,  Tcl_AsyncMark,  Tcl_AsyncInvoke,  Tcl_AsyncDelete, Tcl_AsyncReady - handle asynchronous
       events

SYNOPSIS

       #include <tcl.h>

       Tcl_AsyncHandler
       Tcl_AsyncCreate(proc, clientData)

       Tcl_AsyncMark(async)

       int
       Tcl_AsyncInvoke(interp, code)

       Tcl_AsyncDelete(async)

       int
       Tcl_AsyncReady()

ARGUMENTS

       Tcl_AsyncProc *proc (in)                  Procedure to invoke to handle an asynchronous event.

       ClientData clientData (in)                One-word value to pass to proc.

       Tcl_AsyncHandler async (in)               Token for asynchronous event handler.

       Tcl_Interp *interp (in)                   Tcl interpreter in  which  command  was  being  evaluated  when
                                                 handler  was invoked, or NULL if handler was invoked when there
                                                 was no interpreter active.

       int code (in)                             Completion code from command that just completed in interp,  or
                                                 0 if interp is NULL.
________________________________________________________________________________________________________________

DESCRIPTION

       These  procedures  provide  a safe mechanism for dealing with asynchronous events such as signals.  If an
       event such as a signal occurs while a Tcl script is being evaluated then it  is  not  safe  to  take  any
       substantive  action to process the event.  For example, it is not safe to evaluate a Tcl script since the
       interpreter may already be in the middle of evaluating a script; it may not  even  be  safe  to  allocate
       memory,  since  a  memory  allocation could have been in progress when the event occurred.  The only safe
       approach is to set a flag indicating that the event occurred, then handle the event later when the  world
       has returned to a clean state, such as after the current Tcl command completes.

       Tcl_AsyncCreate,  Tcl_AsyncDelete,  and  Tcl_AsyncReady  are  thread sensitive.  They access and/or set a
       thread-specific data structure in the event of a core built with --enable-threads.  The token created  by
       Tcl_AsyncCreate   contains   the   needed   thread  information  it  was  called  from  so  that  calling
       Tcl_AsyncMark(token) will only yield the origin thread into the asynchronous handler.

       Tcl_AsyncCreate creates an asynchronous handler and returns a token for  it.   The  asynchronous  handler
       must be created before any occurrences of the asynchronous event that it is intended to handle (it is not
       safe to create a handler at the time of an event).  When an  asynchronous  event  occurs  the  code  that
       detects  the  event  (such as a signal handler) should call Tcl_AsyncMark with the token for the handler.
       Tcl_AsyncMark will mark the handler as ready to execute, but it will not invoke the handler  immediately.
       Tcl will call the proc associated with the handler later, when the world is in a safe state, and proc can
       then carry out the actions associated with the asynchronous event.  Proc should have arguments and result
       that match the type Tcl_AsyncProc:

              typedef int Tcl_AsyncProc(
                      ClientData clientData,
                      Tcl_Interp *interp,
                      int code);

       The clientData will be the same as the clientData argument passed to Tcl_AsyncCreate when the handler was
       created.  If proc is invoked just after a command has completed execution in an interpreter, then  interp
       will  identify  the  interpreter  in which the command was evaluated and code will be the completion code
       returned by that command.  The command's result will be present in the interpreter's result.   When  proc
       returns, whatever it leaves in the interpreter's result will be returned as the result of the command and
       the integer value returned by proc will be used as the new completion code for the command.

       It is also possible for proc to be invoked when no interpreter is active.  This can happen, for  example,
       if an asynchronous event occurs while the application is waiting for interactive input or an X event.  In
       this case interp will be NULL and code will be 0, and the return value from proc will be ignored.

       The procedure Tcl_AsyncInvoke is called to invoke all of the handlers  that  are  ready.   The  procedure
       Tcl_AsyncReady  will  return non-zero whenever any asynchronous handlers are ready;  it can be checked to
       avoid calls to Tcl_AsyncInvoke when there are no ready handlers.  Tcl  calls  Tcl_AsyncReady  after  each
       command  is evaluated and calls Tcl_AsyncInvoke if needed.  Applications may also call Tcl_AsyncInvoke at
       interesting times for that application.  For example, Tcl's event handler calls Tcl_AsyncReady after each
       event  and  calls  Tcl_AsyncInvoke  if needed.  The interp and code arguments to Tcl_AsyncInvoke have the
       same meaning as for proc:  they identify the active interpreter, if any, and the completion code from the
       command that just completed.

       Tcl_AsyncDelete  removes an asynchronous handler so that its proc will never be invoked again.  A handler
       can be deleted even when ready, and it will still not be invoked.

       If multiple handlers become active at the same time, the handlers are invoked  in  the  order  they  were
       created  (oldest  handler  first).   The code and the interpreter's result for later handlers reflect the
       values returned by earlier handlers, so that the most recently created handler has  last  say  about  the
       interpreter's  result  and  completion  code.  If new handlers become ready while handlers are executing,
       Tcl_AsyncInvoke will invoke them all;  at each point  it  invokes  the  highest-priority  (oldest)  ready
       handler, repeating this over and over until there are no longer any ready handlers.

WARNING

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

KEYWORDS

       asynchronous event, handler, signal, Tcl_SaveInterpState, thread