plucky (3) Tcl_AsyncCreate.3tcl.gz

NAME

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

SYNOPSIS

       #include <tcl.h>

       Tcl_AsyncHandler
       Tcl_AsyncCreate(proc, clientData)

       void
       Tcl_AsyncMark(async)

       int
       Tcl_AsyncMarkFromSignal(async, sigNumber)

       int
       Tcl_AsyncInvoke(interp, code)

       void
       Tcl_AsyncDelete(async)

       int
       Tcl_AsyncReady()

ARGUMENTS

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

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

       Tcl_AsyncHandler async (in)               Token for asynchronous event handler.

       int sigNumber (in)                        POSIX signal number, when used in a signal context.

       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_AsyncMarkFromSignal or Tcl_AsyncMark with this 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 POSIX signal handler) should call Tcl_AsyncMarkFromSignal with the token for
       the handler and the POSIX signal number. The return value of this function is true, when the handler will
       be  marked,  false  otherwise.   For  non-signal  contexts,  Tcl_AsyncMark  serves  the   same   purpose.
       Tcl_AsyncMarkFromSignal  and Tcl_AsyncMark will mark the handler as ready to execute, but 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(
                      void *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