Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tcl_AsyncCreate(3)	    Tcl	Library	Procedures	    Tcl_AsyncCreate(3)

______________________________________________________________________________

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 com-
						 mand was being	evaluated when
						 handler  was invoked, or NULL
						 if handler was	 invoked  when
						 there	was no interpreter ac-
						 tive.

       int code	(in)				 Completion code from  command
						 that  just  completed	in in-
						 terp, 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  substan-
       tive action to process the event.  For example, it is not safe to eval-
       uate 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  oc-
       curred.	 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	sensi-
       tive.  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_Async-
       Mark 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  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  re-
       turned  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  ac-
       tive.   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  asynchro-
       nous  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

Tcl				      7.0		    Tcl_AsyncCreate(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | WARNING | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_AsyncCreate.tcl87&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help