TclAsyncCreate(3) Tcl Library Procedures TclAsyncCreate(3)

NAME
       TclAsyncCreate,   TclAsyncMark,   TclAsyncInvoke,   TclAsyncDelete,
       TclAsyncReady - handle asynchronous events

SYNOPSIS
       ##iinncclluuddee <>

       TclAsyncHandler
       TTccllAAssyynnccCCrreeaattee(proc, clientData)

       TTccllAAssyynnccMMaarrkk(async)

       int
       TTccllAAssyynnccIInnvvookkee(interp, code)

       TTccllAAssyynnccDDeelleettee(async)

       int
       TTccllAAssyynnccRReeaaddyy()

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

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

       TclAsyncHandler   async        (in)      Token for asynchronous  event
                                                 handler.

       TclInterp         *interp      (in)      Tcl interpreter in which com-
                                                 mand 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 isn't safe to take any substan-
       tive action to process the event.  For example, it isn't safe to evalu-
       ate  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.

       TTccllAAssyynnccCCrreeaattee, TTccllAAssyynnccDDeelleettee, and TTccllAAssyynnccRReeaaddyy are thread  sensi-
       tive.   They  access and/or set a thread-specific data structure in the
       event  of  an  -enable-thread  built  core.   The  token  created   by
       TclAsyncCreate  contains  the  needed thread information it was called
       from so that calling TclAsyncMark(token) will only  yield  the  origin
       thread into the AsyncProc.

       TTccllAAssyynnccCCrreeaattee 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 TTccllAAssyynnccMMaarrkk with the token for the  handler.   TTccllAAssyynncc-
       MMaarrkk  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 TTccllAAssyynnccPPrroocc:
              typedef int TclAsyncProc(
                ClientData clientData,
                TclInterp *interp,
                int code);
       The  clientData  will  be the same as the clientData argument passed to
       TTccllAAssyynnccCCrreeaattee 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 com-
       mand'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  TTccllAAssyynnccIInnvvookkee is called to invoke all of the handlers
       that are ready.  The  procedure  TTccllAAssyynnccRReeaaddyy  will  return  non-zero
       whenever  any  asynchronous  handlers  are ready;  it can be checked to
       avoid calls to TTccllAAssyynnccIInnvvookkee when there are no ready  handlers.   Tcl
       calls   TTccllAAssyynnccRReeaaddyy  after  each  command  is  evaluated  and  calls
       TTccllAAssyynnccIInnvvookkee if needed.  Applications may also call  TTccllAAssyynnccIInnvvookkee
       at  interesting  times  for that application.  For example, Tcl's event
       handler calls TTccllAAssyynnccRReeaaddyy after each event and calls TTccllAAssyynnccIInnvvookkee
       if  needed.   The interp and code arguments to TTccllAAssyynnccIInnvvookkee have the
       same meaning as for proc:  they identify  the  active  interpreter,  if
       any, and the completion code from the command that just completed.

       TTccllAAssyynnccDDeelleettee  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, TTccllAAssyynnccIInnvvookkee
       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.


WWAARRNNIINNGG
       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  result  plus  the
       values  of the variables eerrrroorrIInnffoo and eerrrroorrCCooddee (this can be done, for
       example, by storing them in dynamic strings).   When  the  asynchronous
       handler  is finished it should restore the interpreter's result, eerrrroorr-
       IInnffoo, and eerrrroorrCCooddee, and return the code argument.


KKEEYYWWOORRDDSS
       asynchronous event, handler, signal



Tcl                                   7.0                   TclAsyncCreate(3)