Notifier man page on DigitalUNIX

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

Notifier(3)		    Tcl Library Procedures		   Notifier(3)


NAME									       │
       Tcl_CreateEventSource,	 Tcl_DeleteEventSource,	  Tcl_SetMaxBlockTime, │
       Tcl_QueueEvent,	 Tcl_DeleteEvents,   Tcl_WaitForEvent,	 Tcl_SetTimer, │
       Tcl_ServiceAll,	Tcl_ServiceEvent,  Tcl_GetServiceMode, Tcl_SetService‐ │
       Mode - the event queue and notifier interfaces			       │

SYNOPSIS								       │
       #include <tcl.h>							       │

       Tcl_CreateEventSource(setupProc, checkProc, clientData)		       │

       Tcl_DeleteEventSource(setupProc, checkProc, clientData)		       │

       Tcl_SetMaxBlockTime(timePtr)					       │

       Tcl_QueueEvent(evPtr, position)					       │

       Tcl_DeleteEvents(deleteProc, clientData)				       │

       int								       │
       Tcl_WaitForEvent(timePtr)Tcl_SetTimer(timePtr)						       │

       int								       │
       Tcl_ServiceAll()							       │

       int								       │
       Tcl_ServiceEvent(flags)						       │

       int								       │
       Tcl_GetServiceMode()						       │

       int								       │
       Tcl_EventSetupProc   *setupProc	 (in)	   Procedure to invoke to pre‐
						   pare	  for  event  wait  in

       Tcl_EventCheckProc   *checkProc	 (in)	   Procedure		   for
						   Tcl_DoOneEvent   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  setupProc,	check‐
						   Proc, or deleteProc.

       Tcl_Time		    *timePtr	 (in)	   Indicates	the    maximum
						   amount of time to wait  for
						   an  event.	This is speci‐
						   fied as  an	interval  (how
						   long to wait), not an abso‐
						   lute time (when to wakeup).
						   If  the  pointer  passed to
						   Tcl_WaitForEvent  is	 NULL,
						   it  means there is no maxi‐
						   mum wait time:   wait  for‐
						   ever 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 call‐
						   er	using	Tcl_Alloc   or

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

       int		    flags	 (in)	   What	 types	of  events  to
						   service.   These  flags are
						   the same as those passed to

       Tcl_EventDeleteProc  *deleteProc	 (in)	   Procedure   to  invoke  for
						   each	  queued   event    in
						   Tcl_DeleteEvents.	       │

       int		    mode	 (in)				       │
						   Inidicates  whether	events │
						   should   be	 serviced   by │
						   Tcl_ServiceAll.    Must  be │
						   one of TCL_SERVICE_NONE  or │

       The interfaces described here are used to customize the Tcl event loop. │
       The two most common customizations are to add new sources of events and │
       to  merge Tcl's event loop with some other event loop, such as one pro‐ │
       vided by an application in which Tcl is embedded.  Each of these	 tasks │
       is described in a separate section below.

       The  procedures	in  this  manual  entry 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_CreateTimerHandler  procedure and the after
	      command, and there is a file event source	 that  implements  the
	      Tcl_CreateFileHandler  procedure	on  Unix  systems.   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.   The  procedures
	      Tcl_CreateEventSource,   Tcl_DeleteEventSource,	and   Tcl_Set‐
	      MaxBlockTime, Tcl_QueueEvent, and Tcl_DeleteEvents are used pri‐
	      marily by event sources.

       [2]    The  event queue: there is a single queue for the whole applica‐
	      tion, containing events that have been detected but not yet ser‐
	      viced.   Event  sources place events onto the queue so that they
	      may be processed in order at appropriate times during the	 event
	      loop. The event queue guarantees a fair discipline of event han‐
	      dling, so that no event source can starve the others.   It  also
	      allows  events  to  be  saved  for  servicing  at a future time. │
	      Tcl_QueueEvent is used  (primarily  by  event  sources)  to  add │
	      events to the event queue and Tcl_DeleteEvents is used to remove │
	      events from the queue without processing them.		       │

       [3]								       │
	      The event loop: in order	to  detect  and	 process  events,  the │
	      application enters a loop that waits for events to occur, places │
	      them on the event queue, and then processes them.	 Most applica‐ │
	      tions  will  do  this  by	 calling the procedure Tcl_DoOneEvent, │
	      which is described in a separate manual entry.		       │

       Most Tcl applications need not worry about any of the internals of  the │
       Tcl  notifier.	However, the notifier now has enough flexibility to be │
       retargeted either for a new platform or to use an external  event  loop │
       (such as the Motif event loop, when Tcl is embedded in a Motif applica‐ │
       tion).  The procedures Tcl_WaitForEvent and Tcl_SetTimer	 are  normally │
       implemented  by	Tcl, but may be replaced with new versions to retarget │
       the notifier (the Tcl_Sleep, Tcl_CreateFileHandler, and Tcl_DeleteFile‐ │
       Handler	must  also  be replaced; see CREATING A NEW NOTIFIER below for │
       details).  The procedures Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetSer‐ │
       viceMode,  and  Tcl_SetServiceMode  are	provided to help connect Tcl's │
       event loop to an external event loop such as Motif's.		       │

NOTIFIER BASICS								       │
       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.  It does this	 by  calling  Tcl_Ser‐ │
	      viceEvent and passing in the flags argument.

       [2]    Prepare  to  block  for  an  event.   To do this, Tcl_DoOneEvent
	      invokes a setup procedure	 in  each  event  source.   The	 event
	      source  will  perform  event-source  specific initialization and │
	      possibly call Tcl_SetMaxBlockTime to limit  how  long  Tcl_Wait‐
	      ForEvent will block if no new events occur.

       [3]    Call  Tcl_WaitForEvent.	This  procedure is implemented differ‐
	      ently on different platforms;  it waits for an event  to	occur,
	      based  on the information 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 hap‐
	      pened, such as a file becoming readable or the interval given by
	      timePtr  expiring.   If there are no events for Tcl_WaitForEvent
	      to wait for, so that it would block  forever,  then  it  returns
	      immediately and Tcl_DoOneEvent returns 0.

       [4]    Call  a  check procedure in each event source.  The check proce‐
	      dure determines whether any events of interest  to  this	source
	      occurred.	 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.

       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,
       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 infor‐
       mation 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 be 0 (Tcl_DoOneEvent  replaces  0	with  TCL_ALL_EVENTS).	 Flags
       indicates  what kinds of events should be considered; if the bit corre‐
       sponding 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 make sure that  the  application  wakes  up  when
       events  of  the	desired type occur.  This is typically done in a plat‐
       form-dependent fashion.	For example, under Unix an event source	 might
       call Tcl_CreateFileHandler; under Windows it might request notification
       with a Windows event.  For timer-driven event  sources  such  as	 timer
       events  or any polled event, the event source can call Tcl_SetMaxBlock‐
       Time to force the application to wake up after a specified time even if
       no  events have occurred.  If no event source calls Tcl_SetMaxBlockTime │
       then Tcl_WaitForEvent will wait as long as necessary for	 an  event  to │
       occur;  otherwise,  it  will only wait as long as the shortest interval │
       passed to Tcl_SetMaxBlockTime by one of the event sources.  If an event │
       source knows that it already has events ready to report, it can request │
       a zero maximum block time.  For example, the setup procedure for the  X │
       event source looks to see if there are events already queued.  If there │
       are, it calls Tcl_SetMaxBlockTime with a 0 block time so that Tcl_Wait‐ │
       ForEvent	 does  not  block if there is no new data on the X connection.
       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_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.

       If   the	  application	uses   an  external  event  loop  rather  than │
       Tcl_DoOneEvent, the event sources may need to call  Tcl_SetMaxBlockTime │
       at other times.	For example, if a new event handler is registered that │
       needs to poll for events, the event source may call Tcl_SetMaxBlockTime │
       to  set the block time to zero to force the external event loop to call │
       Tcl.  In this case, Tcl_SetMaxBlockTime invokes Tcl_SetTimer  with  the │
       shortest	 interval  seen	 since	the  last  call	 to  Tcl_DoOneEvent or │
       Tcl_ServiceAll.							       │

       In addition to the generic procedure Tcl_SetMaxBlockTime,  other	 plat‐ │
       form-specific  procedures may also be available for setupProc, if there │
       is additional information needed by Tcl_WaitForEvent on that  platform. │
       For example, on Unix systems the Tcl_CreateFileHandler interface can be │
       used to wait for file events.

       The second procedure provided by each event source is its check	proce‐
       dure,  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.

       If an event source's check procedure detects an interesting  event,  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 informa‐
       tion 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	struc‐
       ture  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;
       The  event source must fill in the proc field of the event before call‐
       ing 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 positions, 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 posi‐
			       tion  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 4 above) │
       Tcl_ServiceEvent 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_ServiceEvent;  this is used	by  the	 event │
       source to return immediately if its events are not relevant.

       It is up to proc to handle the event, typically by invoking 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 indi‐
       cate that the event should be deferred for processing later;   in  this │
       case  Tcl_ServiceEvent  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_ServiceEvent 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_ServiceEvent, not by the event source.			       │

       Tcl_DeleteEvents	 can  be  used to explicitly remove one or more events │
       from the event queue.  Tcl_DeleteEvents calls proc for  each  event  in │
       the queue, deleting those for with the procedure returns 1.  Events for │
       which the procedure returns 0 are left in the queue.  Proc should match │
       the following prototype:						       │
	      typedef int Tcl_EventDeleteProc(				       │
		Tcl_Event *evPtr,					       │
		ClientData clientData);					       │
       The  clientData argument will be the same as the clientData argument to │
       Tcl_DeleteEvents; it is typically used to point to private  information │
       managed by the event source.  The evPtr will point to the next event in │
       the queue.

       The notifier consists of all the procedures described  in  this	manual
       entry,  plus  Tcl_DoOneEvent  and Tcl_Sleep, which are available on all │
       platforms, and Tcl_CreateFileHandler and	 Tcl_DeleteFileHandler,	 which │
       are  Unix-specific.  Most of these procedures are generic, in that they │
       are the same for all notifiers.	However, five of  the  procedures  are │
       notifier-dependent: Tcl_SetTimer, Tcl_Sleep, Tcl_WaitForEvent, Tcl_Cre‐ │
       ateFileHandler and Tcl_DeleteFileHandler.  To support a new platform or │
       to  integrate  Tcl  with	 an  application-specific event loop, you must │
       write new versions of these procedures.				       │

       Tcl_WaitForEvent is the lowest-level procedure in the notifier;	it  is │
       responsible  for waiting for an ``interesting'' 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 timePtr │
       argument to Tcl_WaitForEvent gives the maximum time  to	block  for  an │
       event,  based  on calls to Tcl_SetMaxBlockTime made by setup procedures │
       and on other information (such as the TCL_DONT_WAIT bit in flags).      │

       Ideally, Tcl_WaitForEvent should only wait for an event	to  occur;  it │
       should  not actually process the event in any way.  Later on, the event │
       sources will process the raw events and create Tcl_Events on the	 event │
       queue  in their checkProc procedures.  However, on some platforms (such │
       as Windows) this isn't possible; events may be processed	 in  Tcl_Wait‐ │
       ForEvent, including queuing Tcl_Events and more (for example, callbacks │
       for native widgets may be invoked).  The return	value  from  Tcl_Wait‐ │
       ForEvent	 must  be  either  0,  1, or -1.  On platforms such as Windows │
       where events get processed in Tcl_WaitForEvent, a  return  value	 of  1 │
       means  that  there  may	be more events still pending that haven't been │
       processed.  This is a sign to the caller that it	 must  call  Tcl_Wait‐ │
       ForEvent	 again	if  it	wants  all pending events to be processed. A 0 │
       return value means that calling Tcl_WaitForEvent again  will  not  have │
       any effect: either this is a platform where Tcl_WaitForEvent only waits │
       without doing any event processing, or Tcl_WaitForEvent knows for  sure │
       that  there  are	 no  additional	 events	 to  process (e.g. it returned │
       because the time elapsed).  Finally, a return value of  -1  means  that │
       the  event  loop	 is  no	 longer operational and the application should │
       probably unwind and terminate.	Under  Windows	this  happens  when  a │
       WM_QUIT	message	 is  received;	under  Unix  it happens when Tcl_Wait‐ │
       ForEvent would have waited forever because there were no	 active	 event │
       sources and the timeout was infinite.				       │

       If  the notifier will be used with an external event loop, then it must │
       also support the Tcl_SetTimer interface.	 Tcl_SetTimer  is  invoked  by │
       Tcl_SetMaxBlockTime   whenever  the  maximum  blocking  time  has  been │
       reduced.	 Tcl_SetTimer should arrange for the external  event  loop  to │
       invoke  Tcl_ServiceAll  after  the specified interval even if no events │
       have occurred.  This interface is needed because Tcl_WaitForEvent isn't │
       invoked	when  there  is	 an external event loop.  If the notifier will │
       only be used from Tcl_DoOneEvent, then Tcl_SetTimer need	 not  do  any‐ │
       thing.								       │

       On  Unix	 systems,  the	file  event source also needs support from the │
       notifier.  The file event source consists of the	 Tcl_CreateFileHandler │
       and Tcl_DeleteFileHandler procedures, which are described elsewhere.    │

       The Tcl_Sleep and Tcl_DoOneEvent interfaces are described elsewhere.    │

       The  easiest way to create a new notifier is to look at the code for an │
       existing notifier, such as the files unix/tclUnixNotfy.c or win/tclWin‐ │
       Notify.c in the Tcl source distribution.				       │

       The  notifier  interfaces are designed so that Tcl can be embedded into │
       applications that have their own private event loops.   In  this	 case, │
       the  application	 does  not  call  Tcl_DoOneEvent except in the case of │
       recursive event loops such as calls  to	the  Tcl  commands  update  or │
       vwait.	Most  of  the  time is spent in the external event loop of the │
       application.  In this case the notifier must arrange for	 the  external │
       event  loop to call back into Tcl when something happens on the various │
       Tcl event sources.  These callbacks should arrange for appropriate  Tcl │
       events to be placed on the Tcl event queue.			       │

       Because the external event loop is not calling Tcl_DoOneEvent on a reg‐ │
       ular basis, it is up to the notifier to arrange for Tcl_ServiceEvent to │
       be called whenever events are pending on the Tcl event queue.  The eas‐ │
       iest way to do this is to invoke Tcl_ServiceAll	at  the	 end  of  each │
       callback	 from  the  external event loop.  This will ensure that all of │
       the event sources are polled, any queued events are serviced,  and  any │
       pending	idle  handlers	are  processed before returning control to the │
       application.  In addition, event sources that need to poll  for	events │
       can  call  Tcl_SetMaxBlockTime to force the external event loop to call │
       Tcl even if no events are available on the system event queue.	       │

       As a side effect of processing events detected  in  the	main  external │
       event  loop,  Tcl  may invoke Tcl_DoOneEvent to start a recursive event │
       loop in commands like vwait.  Tcl_DoOneEvent will invoke	 the  external │
       event  loop, which will result in callbacks as described in the preced‐ │
       ing paragraph, which will result in calls to Tcl_ServiceAll.   However, │
       in  these  cases it is undesirable to service events in Tcl_ServiceAll. │
       Servicing events there is unnecessary because control will  immediately │
       return  to  the	external event loop and hence to Tcl_DoOneEvent, which │
       can service the events itself.  Furthermore, Tcl_DoOneEvent is supposed │
       to  service  only  a single event, whereas Tcl_ServiceAll normally ser‐ │
       vices all pending events.  To  handle  this  situation,	Tcl_DoOneEvent │
       sets a flag for Tcl_ServiceAll that causes it to return without servic‐ │
       ing any events.	This flag is called the service	 mode;	Tcl_DoOneEvent │
       restores it to its previous value before it returns.		       │

       In  some cases, however, it may be necessary for Tcl_ServiceAll to ser‐ │
       vice events even when it has been invoked  from	Tcl_DoOneEvent.	  This │
       happens	when  there is yet another recursive event loop invoked via an │
       event handler called by Tcl_DoOneEvent (such as one that is part	 of  a │
       native  widget).	 In this case, Tcl_DoOneEvent may not have a chance to │
       service events so Tcl_ServiceAll must service them all.	Any  recursive │
       event loop that calls an external event loop rather than Tcl_DoOneEvent │
       must reset the service  mode  so	 that  all  events  get	 processed  in │
       Tcl_ServiceAll.	This is done by invoking the Tcl_SetServiceMode proce‐ │
       dure.  If Tcl_SetServiceMode is passed TCL_SERVICE_NONE, then calls  to │
       Tcl_ServiceAll  will  return immediately without processing any events. │
       If Tcl_SetServiceMode is passed TCL_SERVICE_ALL, then calls to Tcl_Ser‐ │
       viceAll	will behave normally.  Tcl_SetServiceMode returns the previous │
       value of the service mode, which should be restored when the  recursive │
       loop  exits.   Tcl_GetServiceMode returns the current value of the ser‐ │
       vice mode.

       event, notifier, event queue, event sources, file events, timer,	 idle,
       service mode

Tcl				      8.0			   Notifier(3)

List of man pages available for DigitalUNIX

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]
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