Tcl_QueueEvent man page on BSDOS

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDOS logo
[printable version]



Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

_________________________________________________________________

NAME
       Tcl_CreateEventSource,  Tcl_DeleteEventSource,  Tcl_Watch-
       File, Tcl_FileReady, Tcl_SetMaxBlockTime,  Tcl_QueueEvent,
       Tcl_WaitForEvent	 - Event sources, the event notifier, and
       the event queue

SYNOPSIS
       #include <tcl.h>

       Tcl_CreateEventSource(setupProc, checkProc, clientData)

       Tcl_DeleteEventSource(setupProc, checkProc, clientData)

       Tcl_WatchFile(file, mask)

       Tcl_SetMaxBlockTime(timePtr)

       int
       Tcl_FileReady(file, mask)

       Tcl_QueueEvent(evPtr, position)

       int
       Tcl_WaitForEvent(timePtr)

ARGUMENTS
       Tcl_EventSetupProc   *setupProc	 (in)	   Procedure   to
						   invoke to pre-
						   pare for event
						   wait	       in
						   Tcl_DoWhenIdle.

       Tcl_EventCheckProc   *checkProc	 (in)	   Procedure  for
						   Tcl_DoWhenIdle
						   to	   invoke
						   after  waiting
						   for	  events.
						   Checks to  see
						   if  any events
						   have	 occurred
						   and,	  if  so,
						   queues them.

       ClientData	    clientData	 (in)	   Arbitrary one-
						   word	 value to
						   pass to setup-
						   Proc	      and
						   checkProc.

       Tcl_File		    file	 (in)	   Generic   file
						   handle      as
						   returned    by

Tcl			       7.5				1

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

						   Tcl_GetFile.

       int		    mask	 (in)	   Indicates  the
						   events      of
						   interest    on
						   file:       an
						   OR'ed combina-
						   tion	       of
						   TCL_READABLE,
						   TCL_WRITABLE,
						   and TCL_EXCEP-
						   TION.

       Tcl_Time		    *timePtr	 (in)	   Indicates  the
						   maximum amount
						   of	time   to
						   wait	  for  an
						   event.    This
						   is	specified
						   as an interval
						   (how	 long  to
						   wait), not  an
						   absolute  time
						   (when       to
						   wakeup).    If
						   the	  pointer
						   passed      to
						   Tcl_Wait-
						   ForEvent    is
						   NULL, it means
						   there   is  no
						   maximum   wait
						   time:     wait
						   forever     if
						   necessary.

       Tcl_Event	    *evPtr	 (in)	   An	event  to
						   add	 to   the
						   event   queue.
						   The	  storage
						   for	the event
						   must have been |
						   allocated   by |
						   the	   caller |
						   using	  |
						   Tcl_Alloc   or |
						   ckalloc.

       Tcl_QueuePosition    position	 (in)	   Where  to  add
						   the new  event
						   in  the queue:
						   TCL_QUEUE_TAIL,
						   TCL_QUEUE_HEAD,
						   or

Tcl			       7.5				2

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

						   TCL_QUEUE_MARK.

       int		    flags	 (in)	   A copy of  the
						   flags argument
						   passed      to
						   Tcl_DoOneEvent.
_________________________________________________________________

INTRODUCTION
       The procedures described here are the building blocks  out
       of which the Tcl event notifier is constructed.	The event
       notifier is the lowest layer in the Tcl	event  mechanism.
       It consists of three things:

       [1]    Event  sources:	these represent the ways in which
	      events can be generated.	For example, there  is	a
	      timer  event source that implements the Tcl_Create-
	      TimerHandler procedure and the after  command,  and
	      there  is	 a  file event source that implements the
	      Tcl_CreateFileHandler procedure.	An  event  source
	      must work with the notifier to detect events at the
	      right times, record them on the  event  queue,  and
	      eventually  notify  higher-level software that they
	      have occurred.

       [2]    The event queue:	there is a single queue	 for  the
	      whole application, containing events that have been
	      detected but not yet  serviced.	The  event  queue
	      guarantees  a fair discipline of event handling, so
	      that no event source can	starve	the  others.   It
	      also  allows  events to be saved for servicing at a
	      future time.

       [3]    The procedure Tcl_DoOneEvent:   this  is	procedure
	      that  is	invoked	 by  the  application  to service
	      events.  It works with the event	sources	 and  the
	      event  queue to detect and handle events, and calls
	      Tcl_WaitForEvent to actually wait for an	event  to
	      occur.

       The easiest way to understand how the notifier works is to
       consider	 what  happens	when  Tcl_DoOneEvent  is  called.
       Tcl_DoOneEvent  is  passed a flags argument that indicates
       what sort of events it is OK to process and  also  whether
       or  not	to  block if no events are ready.  Tcl_DoOneEvent
       does the following things:

       [1]    Check the event queue to see  if	it  contains  any
	      events  that  can	 be serviced.  If so, service the
	      first possible event, remove it from the queue, and
	      return.

       [2]    Prepare  to  block  for  an  event.   To	do  this,

Tcl			       7.5				3

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

	      Tcl_DoOneEvent invokes a setup  procedure	 in  each
	      event  source.   The  event source will call proce-
	      dures like Tcl_WatchFile and Tcl_SetMaxBlockTime to
	      indicate	what  low-level	 events	 to  look  for in
	      Tcl_WaitForEvent.

       [3]    Call Tcl_WaitForEvent.  This  procedure  is  imple-
	      mented  differently  on  different  platforms;   it
	      waits for an event to occur, based on the	 informa-
	      tion  provided  by the event sources.  It may cause
	      the application to block if  timePtr  specifies  an
	      interval	other  than  0.	 Tcl_WaitForEvent returns
	      when something has happened, such as a file  becom-
	      ing  readable  or	 the  interval	given  by timePtr
	      expiring.	 If there are  no  events  for	Tcl_Wait-
	      ForEvent	to  wait for, so that it would block for-
	      ever,   then    it    returns    immediately    and
	      Tcl_DoOneEvent returns 0.

       [4]    Call  a  check procedure in each event source.  The
	      check procedure determines whether  any  events  of
	      interest	to  this source occurred (e.g. by calling
	      Tcl_FileReady).  If so, the events are added to the
	      event queue.

       [5]    Check  the  event	 queue	to see if it contains any
	      events that can be serviced.  If	so,  service  the
	      first possible event, remove it from the queue, and
	      return.

       [6]    See if there are idle callbacks  pending.	  If  so,
	      invoke all of them and return.

       [7]    Either  return  0	 to  indicate that no events were
	      ready, or go back	 to  step  [2]	if  blocking  was
	      requested by the caller.

       The  procedures	in  this file allow you to do two things.
       First, they allow you to create new event sources, such as
       one  for	 UNIX  signals or one to notify when subprocesses
       have exited.  Second, the procedures can be used to  build
       a  new version of Tcl_DoOneEvent.  This might be necessary
       to support a new operating system with different low-level
       event  reporting	 mechanisms,  or it might be necessary to
       merge Tcl's event loop with that	 of  some  other  toolkit
       like Xt.

CREATING A NEW EVENT SOURCE
       An  event  source  consists of three procedures invoked by
       the  notifier,  plus  additional	 C  procedures	that  are
       invoked	by  higher-level code to arrange for event-driven
       callbacks.  The three procedures called	by  the	 notifier
       consist of the setup and check procedures described above,

Tcl			       7.5				4

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

       plus an additional procedure that is invoked when an event
       is removed from the event queue for servicing.

       The  procedure  Tcl_CreateEventSource  creates a new event
       source.	Its arguments specify  the  setup  procedure  and
       check  procedure	 for  the event source.	 SetupProc should
       match the following prototype:
	      typedef void Tcl_EventSetupProc(
		ClientData clientData,
		int flags);
       The clientData argument will be the same as the clientData
       argument	 to  Tcl_CreateEventSource;  it is typically used
       to point to  private  information  managed  by  the  event
       source.	 The flags argument will be the same as the flags
       argument passed to  Tcl_DoOneEvent  except  that	 it  will
       never	by    0	   (Tcl_DoOneEvent    replaces	 0   with
       TCL_ALL_EVENTS).	 Flags indicates  what	kinds  of  events
       should  be  considered;	if  the bit corresponding to this
       event source isn't set, the  event  source  should  return
       immediately without doing anything.  For example, the file
       event source checks for the TCL_FILE_EVENTS bit.

       SetupProc's job is to  provide  information  to	Tcl_Wait-
       ForEvent	 about	how  to wait for events.  It usually does
       this by calling Tcl_WatchFile or Tcl_SetMaxBlockTime.  For
       example, setupProc can call Tcl_WatchFile to indicate that
       Tcl_WaitForEvent should return when the	conditions  given
       by  the	mask  argument	become true for the file given by
       file.  The  UNIX	 version  of  Tcl_WaitForEvent	uses  the
       information  passed to Tcl_WatchFile to set the file masks
       for  select,  which  it	uses  to  wait	for  events.   If
       Tcl_WatchFile  isn't  called  by	 any  event  sources then
       Tcl_WaitForEvent will ignore files while waiting.

       SetupProc can also invoke Tcl_SetMaxBlockTime  to  set  an
       upper  bound  on how long Tcl_WaitForEvent will block.  If
       no event source calls Tcl_SetMaxBlockTime  then	Tcl_Wait-
       ForEvent	 will  wait  as long as necessary for an event to
       occur;  otherwise, it will only wait as long as the short-
       est  interval  passed to Tcl_SetMaxBlockTime by one of the
       event sources.  For example, the timer event  source  uses
       this  procedure	to  limit  the	wait time to the interval
       before the next timer event is ready.  If an event  source
       knows  that  it already has events ready to report, it can
       request a zero maximum block time.  The	timePtr	 argument
       to Tcl_WaitForEvent points to a structure that describes a
       time interval in seconds and microseconds:
	      typedef struct Tcl_Time {
		long sec;
		long usec;
	      } Tcl_Time;
       The usec field should be less than 1000000.

       Information     provided	    to	   Tcl_WatchFile      and

Tcl			       7.5				5

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

       Tcl_SetMaxBlockTime  is	only  used  for	 the next call to
       Tcl_WaitForEvent; it is discarded  after	 Tcl_WaitForEvent
       returns.	  The next time an event wait is done each of the
       event sources' setup procedures will be called again,  and
       they can specify new information for that event wait.

       In  addition  to	 the generic procedures Tcl_WatchFile and
       Tcl_SetMaxBlockTime,  other  platform-specific  procedures
       may  also  be  available	 for setupProc, if there is addi-
       tional information  needed  by  Tcl_WaitForEvent	 on  that
       platform.

       The  second procedure provided by each event source is its
       check procedure, indicated by the  checkProc  argument  to
       Tcl_CreateEventSource.  CheckProc must match the following
       prototype:
	      typedef void Tcl_EventCheckProc(
		ClientData clientData,
		int flags);
       The arguments to this procedure are the same as those  for
       setupProc.   CheckProc  is invoked by Tcl_DoOneEvent after
       it has waited for events.  Presumably at least  one  event
       source  is now prepared to queue an event.  Tcl_DoOneEvent
       calls each of the event sources in turn, so they all  have
       a  chance  to  queue any events that are ready.	The check
       procedure does two things.  First,  it  must  see  if  any
       events have triggered.  Different event sources do this in
       different ways, but the	procedure  Tcl_FileReady  may  be
       useful  for  some  event sources.  It takes as arguments a
       file identifier file and a mask of interesting conditions;
       it  returns  another mask indicating which of those condi-
       tions were found to be present on the file during the most
       recent  call  to	 Tcl_WaitForEvent.  Tcl_WaitForEvent only
       checks a file if Tcl_WatchFile was called by at least  one
       event  source,  so  it  is  possible  for Tcl_FileReady to
       return 0 even if the file is ready.

       If an event  source's  check  procedure	detects	 that  an
       interesting event has occurred, then it must add the event
       to Tcl's event queue.  To do this, the event source  calls
       Tcl_QueueEvent.	 The  evPtr  argument  is  a pointer to a
       dynamically allocated structure containing the event  (see
       below  for  more information on memory management issues).
       Each event source can define its own event structure  with
       whatever	 information  is  relevant  to that event source.
       However, the first element of  the  structure  must  be	a
       structure  of  type  Tcl_Event,	and  the  address of this
       structure is used when  communicating  between  the  event
       source  and the rest of the notifier.  A Tcl_Event has the
       following definition:
	      typedef struct Tcl_Event {
		  Tcl_EventProc *proc;
		  struct Tcl_Event *nextPtr;
	      };

Tcl			       7.5				6

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

       The event source must fill in the proc field of the  event
       before  calling	Tcl_QueueEvent.	  The  nextPtr is used to
       link together the events in the queue and  should  not  be
       modified by the event source.

       An  event  may be added to the queue at any of three posi-
       tions,	depending   on	 the   position	   argument    to
       Tcl_QueueEvent:

       TCL_QUEUE_TAIL	       Add  the	 event at the back of the
			       queue, so that all  other  pending
			       events  will  be	 serviced  first.
			       This is almost  always  the  right
			       place for new events.

       TCL_QUEUE_HEAD	       Add  the event at the front of the
			       queue, so that it will be serviced
			       before all other queued events.

       TCL_QUEUE_MARK	       Add  the event at the front of the
			       queue,  unless  there  are   other
			       events at the front whose position
			       is TCL_QUEUE_MARK;  if so, add the
			       new  event  just	 after	all other
			       TCL_QUEUE_MARK events.  This value
			       of  position  is used to insert an
			       ordered sequence of events at  the
			       front  of  the  queue,  such  as a
			       series of Enter and  Leave  events
			       synthesized   during   a	 grab  or
			       ungrab operation in Tk.

       When it is time to handle an event from the queue (steps 1
       and 5 above) Tcl_DoOneEvent will invoke the proc specified
       in the first queued Tcl_Event structure.	 Proc must  match
       the following prototype:
	      typedef int Tcl_EventProc(
		Tcl_Event *evPtr,
		int flags);
       The  first  argument  to	 proc  is a pointer to the event,
       which will be the  same	as  the	 first	argument  to  the
       Tcl_QueueEvent  call  that  added  the event to the queue.
       The second argument to proc is the flags argument for  the
       current call to Tcl_DoOneEvent;	this is used by the event
       source to return immediately if its events are  not  rele-
       vant.

       It  is up to proc to handle the event, typically by invok-
       ing one or more Tcl commands or C-level	callbacks.   Once
       the  event  source  has	finished  handling  the	 event it
       returns 1 to indicate that the event can be  removed  from
       the  queue.   If	 for some reason the event source decides
       that the event cannot be handled	 at  this  time,  it  may
       return 0 to indicate that the event should be deferred for

Tcl			       7.5				7

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

       processing later;  in this case Tcl_DoOneEvent will go  on
       to  the next event in the queue and attempt to service it.
       There are several reasons why an event source might  defer
       an event.  One possibility is that events of this type are
       excluded by the flags argument.	 For  example,	the  file
       event  source  will always return 0 if the TCL_FILE_EVENTS
       bit isn't set in	 flags.	  Another  example  of	deferring
       events happens in Tk if Tk_RestrictEvents has been invoked
       to defer certain kinds of window events.

       When proc returns 1, Tcl_DoOneEvent will remove the  event
       from  the event queue and free its storage.  Note that the
       storage for an event must be allocated by the event source |
       (using  Tcl_Alloc or the Tcl macro ckalloc) before calling
       Tcl_QueueEvent, but it will be  freed  by  Tcl_DoOneEvent,
       not by the event source.

CREATING A NEW NOTIFIER
       The  notifier  consists of all the procedures described in
       this manual  entry,  plus  Tcl_DoOneEvent  and  Tcl_Sleep.
       Most of these procedures are generic, in that they are the
       same for all platforms.	However, four of  the  procedures
       are   platform-dependent:   Tcl_WatchFile,  Tcl_FileReady,
       Tcl_WaitForEvent, and Tcl_Sleep.	 To support a  new  plat-
       form,  you  must	 write	new versions of these procedures.
       Tcl_WatchFile  and   Tcl_FileReady   have   already   been
       described  previously  in  this document, and Tcl_Sleep is
       described in its own manual entry.

       Tcl_WaitForEvent is  the	 lowest-level  procedure  in  the
       notifier;   it  is responsible for waiting for an ``inter-
       esting'' event to occur or for a	 given	time  to  elapse.
       Before  Tcl_WaitForEvent	 is  invoked,  each  of the event
       sources' setup procedure	 will  have  been  invoked;   the
       setup procedures will have provided information about what
       to wait for by  invoking	 procedures  like  Tcl_WatchFile.
       The timePtr argument to Tcl_WaitForEvent gives the maximum
       time to block for an event, based  on  calls  to	 Tcl_Set-
       MaxBlockTime  made by setup procedures and on other infor-
       mation  (such  as  the  TCL_DONT_WAIT   bit   in	  flags).
       Tcl_WaitForEvent	 uses information saved by Tcl_WatchFile,
       plus the timePtr argument to decide what to wait	 for  and
       how  long  to  block.  It returns TCL_OK as soon as one of
       the specified events has occurred or the given  amount  of
       time has elapsed.  However, if there are no event handlers
       (neither Tcl_WatchFile nor  Tcl_SetMaxBlockTime	has  been
       called  since  the last call to Tcl_WaitForEvent), so that
       the procedure would block forever, then it returns immedi-
       ately with a result of TCL_ERROR.

       The easiest way to create a new notifier is to look at the
       code  for  an  existing	notifier,  such	 as   the   files
       generic/tclNotify.c and unix/tclUnixNotfy.c.

Tcl			       7.5				8

Tcl_CreateEventSource(Tcl Library ProceduTcl_CreateEventSource(3)

KEYWORDS
       block  time,  event  notifier, event queue, event sources,
       file events

Tcl			       7.5				9

[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server BSDOS

List of man pages available for BSDOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net