DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

Tcl_WaitForEvent(3tcl)




Notifier(3)          Tcl Library Procedures           Notifier(3)

_________________________________________________________________


NAME

     Tcl_CreateEventSource,                Tcl_DeleteEventSource,
     Tcl_SetMaxBlockTime,  Tcl_QueueEvent,  Tcl_ThreadQueueEvent,
     Tcl_ThreadAlert,   Tcl_GetCurrentThread,   Tcl_DeleteEvents,
     Tcl_InitNotifier,   Tcl_FinalizeNotifier,  Tcl_WaitForEvent,
     Tcl_AlertNotifier,       Tcl_SetTimer,       Tcl_ServiceAll,
     Tcl_ServiceEvent,  Tcl_GetServiceMode,  Tcl_SetServiceMode -
     the event queue and notifier interfaces


SYNOPSIS

     #include <tcl.h>

     void
     Tcl_CreateEventSource(setupProc, checkProc, clientData)

     void
     Tcl_DeleteEventSource(setupProc, checkProc, clientData)

     void
     Tcl_SetMaxBlockTime(timePtr)

     void
     Tcl_QueueEvent(evPtr, position)

     void
     Tcl_ThreadQueueEvent(threadId, evPtr, position)

     void
     Tcl_ThreadAlert(threadId)

     Tcl_ThreadId
     Tcl_GetCurrentThread()

     void
     Tcl_DeleteEvents(deleteProc, clientData)

     ClientData
     Tcl_InitNotifier()

     void
     Tcl_FinalizeNotifier(clientData)

     int
     Tcl_WaitForEvent(timePtr)

     void
     Tcl_AlertNotifier(clientData)

     void
     Tcl_SetTimer(timePtr)

Tcl                     Last change: 8.1                        1

Notifier(3)          Tcl Library Procedures           Notifier(3)

     int
     Tcl_ServiceAll()

     int
     Tcl_ServiceEvent(flags)

     int
     Tcl_GetServiceMode()

     int
     Tcl_SetServiceMode(mode)

     void
     Tcl_ServiceModeHook(mode)

     void
     Tcl_SetNotifier(notifierProcPtr)


ARGUMENTS

     Tcl_EventSetupProc *setupProc (in)                 Procedure
                                                        to invoke
                                                        to
                                                        prepare
                                                        for event
                                                        wait   in
                                                        Tcl_DoOneEvent.

     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,
                                                        checkProc,

Tcl                     Last change: 8.1                        2

Notifier(3)          Tcl Library Procedures           Notifier(3)

                                                        or
                                                        deleteProc.

     Tcl_Time *timePtr (in)                             Indicates
                                                        the  max-
                                                        imum
                                                        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_WaitForEvent
                                                        is  NULL,
                                                        it  means
                                                        there  is
                                                        no   max-
                                                        imum wait
                                                        time:
                                                        wait for-
                                                        ever   if
                                                        neces-
                                                        sary.

     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

Tcl                     Last change: 8.1                        3

Notifier(3)          Tcl Library Procedures           Notifier(3)

                                                        ckalloc.

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

     Tcl_ThreadId threadId (in)                         A  unique
                                                        identif-
                                                        ier for a
                                                        thread.

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

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

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

     Tcl_NotifierProcs* notifierProcPtr (in)            Structure
                                                        of  func-
                                                        tion
                                                        pointers

Tcl                     Last change: 8.1                        4

Notifier(3)          Tcl Library Procedures           Notifier(3)

                                                        describ-
                                                        ing
                                                        notifier
                                                        pro-
                                                        cedures
                                                        that  are
                                                        to
                                                        replace
                                                        the  ones
                                                        installed
                                                        in    the
                                                        execut-
                                                        able.
                                                        See
                                                        REPLACING
                                                        THE
                                                        NOTIFIER
                                                        for
                                                        details.
_________________________________________________________________


INTRODUCTION

     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 provided by an applica-
     tion 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  mechan-
     ism.  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  pro-
          cedure and the after command, and there is a file event
          source that implements the  Tcl_CreateFileHandler  pro-
          cedure 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_SetMaxBlockTime,
          Tcl_QueueEvent, and Tcl_DeleteEvents are used primarily
          by event sources.

     [2]  The event queue: for non-threaded  applications,  there
          is a single queue for the whole application, containing
          events that have been detected but  not  yet  serviced.

Tcl                     Last change: 8.1                        5

Notifier(3)          Tcl Library Procedures           Notifier(3)

          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 dis-
          cipline 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.  Threaded  applications
          work  in  a  similar  manner,  except  that  there is a
          separate event queue for each thread containing  a  Tcl
          interpreter.   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.  In a threaded  applica-
          tion,  Tcl_QueueEvent  adds  an  event  to  the current
          thread's queue, and Tcl_ThreadQueueEvent adds an  event
          to a queue in a specific thread.

     [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 applications will do this by cal-
          ling the procedure Tcl_DoOneEvent, which  is  described
          in a separate manual entry.

     Most Tcl applications need not worry about any of the inter-
     nals  of  the  Tcl  notifier.  However, the notifier now has
     enough flexibility to be retargeted either for a  new  plat-
     form  or  to  use  an external event loop (such as the Motif
     event loop, when Tcl is embedded in  a  Motif  application).
     The  procedures  Tcl_WaitForEvent  and Tcl_SetTimer are nor-
     mally implemented by Tcl, but may be replaced with new  ver-
     sions   to  retarget  the  notifier  (the  Tcl_InitNotifier,
     Tcl_AlertNotifier,     Tcl_FinalizeNotifier,      Tcl_Sleep,
     Tcl_CreateFileHandler,  and  Tcl_DeleteFileHandler must also
     be replaced; see CREATING A NEW NOTIFIER below for details).
     The     procedures     Tcl_ServiceAll,     Tcl_ServiceEvent,
     Tcl_GetServiceMode, 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 possi-
          ble event, remove it from the queue,  and  return.   It
          does  this  by  calling Tcl_ServiceEvent and passing in
          the flags argument.

Tcl                     Last change: 8.1                        6

Notifier(3)          Tcl Library Procedures           Notifier(3)

     [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_WaitForEvent
          will block if no new events occur.

     [3]  Call Tcl_WaitForEvent.  This procedure  is  implemented
          differently  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 happened,
          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
          procedure  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 possi-
          ble 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.


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,  plus  an  addi-
     tional  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);

Tcl                     Last change: 8.1                        7

Notifier(3)          Tcl Library Procedures           Notifier(3)

     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  be  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 is not 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 platform-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_SetMaxBlockTime
     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 exam-
     ple, 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_WaitForEvent 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

Tcl                     Last change: 8.1                        8

Notifier(3)          Tcl Library Procedures           Notifier(3)

     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 platform-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  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.

     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  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 struc-
     ture 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_EventProc *proc;
              struct Tcl_Event *nextPtr;
          } Tcl_Event;
     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                     Last change: 8.1                        9

Notifier(3)          Tcl Library Procedures           Notifier(3)

     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  syn-
                             thesized 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 can-
     not  be  handled  at  this time, it may return 0 to indicate
     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 rea-
     sons  why  an event source might defer an event.  One possi-
     bility 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 is  not  set  in  flags.
     Another  example  of  deferring  events  happens  in  Tk  if
     Tk_RestrictEvents has been invoked to defer certain kinds of

Tcl                     Last change: 8.1                       10

Notifier(3)          Tcl Library Procedures           Notifier(3)

     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.

     Threaded applications work in a similar manner, except  that
     there is a separate event queue for each thread containing a
     Tcl interpreter.  Calling Tcl_QueueEvent in a  multithreaded
     application adds an event to the current thread's queue.  To
     add   an   event   to   another    thread's    queue,    use
     Tcl_ThreadQueueEvent.   Tcl_ThreadQueueEvent  accepts  as an
     argument a Tcl_ThreadId argument, which uniquely  identifies
     a  thread  in a Tcl application.  To obtain the Tcl_ThreadID
     for the current thread, use  the  Tcl_GetCurrentThread  pro-
     cedure.   (A  thread would then need to pass this identifier
     to other threads for those threads to be able to add  events
     to  its  queue.)   After adding an event to another thread's
     queue, you then typically need to  call  Tcl_ThreadAlert  to
     "wake  up"  that  thread's  notifier  to alert it to the new
     event.

     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 fol-
     lowing 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.

     Tcl_DeleteEventSource  deletes   an   event   source.    The
     setupProc,  checkProc, and clientData arguments must exactly
     match those provided to the  Tcl_CreateEventSource  for  the
     event  source  to  be  deleted.   If  no such source exists,
     Tcl_DeleteEventSource has no effect.


CREATING A NEW NOTIFIER

     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

Tcl                     Last change: 8.1                       11

Notifier(3)          Tcl Library Procedures           Notifier(3)

     all   notifiers.    However,  none  of  the  procedures  are
     notifier-dependent:   Tcl_InitNotifier,   Tcl_AlertNotifier,
     Tcl_FinalizeNotifier,        Tcl_SetTimer,        Tcl_Sleep,
     Tcl_WaitForEvent,                     Tcl_CreateFileHandler,
     Tcl_DeleteFileHandler and Tcl_ServiceModeHook.  To support a
     new platform  or  to  integrate  Tcl  with  an  application-
     specific  event  loop,  you must write new versions of these
     procedures.

     Tcl_InitNotifier initializes the notifier state and  returns
     a  handle  to  the notifier state.  Tcl calls this procedure
     when   initializing   a   Tcl    interpreter.     Similarly,
     Tcl_FinalizeNotifier  shuts down the notifier, and is called
     by Tcl_Finalize when shutting down a Tcl interpreter.

     Tcl_WaitForEvent is the lowest-level procedure in the notif-
     ier;  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  argu-
     ment 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 pro-
     cedures.  However, on some platforms (such as Windows)  this
     is    not    possible;    events   may   be   processed   in
     Tcl_WaitForEvent, including queuing Tcl_Events and more (for
     example,  callbacks for native widgets may be invoked).  The
     return value from Tcl_WaitForEvent 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 have not been pro-
     cessed.  This is a sign to the  caller  that  it  must  call
     Tcl_WaitForEvent  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_WaitForEvent  would have
     waited forever because there were no  active  event  sources
     and the timeout was infinite.

Tcl                     Last change: 8.1                       12

Notifier(3)          Tcl Library Procedures           Notifier(3)

     Tcl_AlertNotifier is used in multithreaded  applications  to
     allow  any  thread  to "wake up" the notifier to alert it to
     new events on its queue.  Tcl_AlertNotifier requires  as  an
     argument the notifier handle returned by Tcl_InitNotifier.

     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
     is not invoked when there is an external event loop.  If the
     notifier  will  only  be  used  from  Tcl_DoOneEvent,   then
     Tcl_SetTimer need not do anything.

     Tcl_ServiceModeHook is called  by  the  platform-independent
     portion  of  the  notifier  when client code makes a call to
     Tcl_SetServiceMode. This hook is provided to support operat-
     ing  systems  that  require  special event handling when the
     application is in a modal loop (the  Windows  notifier,  for
     instance, uses this hook to create a communication window).

     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  in  the  Tcl_CreateFileHandler manual
     page.

     The Tcl_Sleep and Tcl_DoOneEvent interfaces are described in
     their respective manual pages.

     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/tclWinNotify.c in the Tcl  source
     distribution.


REPLACING THE NOTIFIER

     A notifier that has been written according  to  the  conven-
     tions  above  can  also be installed in a running process in
     place of the standard notifier.  This mechanism is  used  so
     that  a  single  executable  can  be used (with the standard
     notifier) as  a  stand-alone  program  and  reused  (with  a
     replacement  notifier  in a loadable extension) as an exten-
     sion to another program, such as a Web browser plugin.

     To do this, the extension makes a  call  to  Tcl_SetNotifier
     passing  a  pointer  to  a Tcl_NotifierProcs data structure.
     The structure has the following layout:
          typedef struct Tcl_NotifierProcs {
              Tcl_SetTimerProc *setTimerProc;

Tcl                     Last change: 8.1                       13

Notifier(3)          Tcl Library Procedures           Notifier(3)

              Tcl_WaitForEventProc *waitForEventProc;
              Tcl_CreateFileHandlerProc *createFileHandlerProc;
              Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
              Tcl_InitNotifierProc *initNotifierProc;
              Tcl_FinalizeNotifierProc *finalizeNotifierProc;
              Tcl_AlertNotifierProc *alertNotifierProc;
              Tcl_ServiceModeHookProc *serviceModeHookProc;
          } Tcl_NotifierProcs;
     Following the call to Tcl_SetNotifier, the pointers given in
     the  Tcl_NotifierProcs  structure  replace whatever notifier
     had been installed in the process.

     It is extraordinarily unwise to replace a running  notifier.
     Normally,  Tcl_SetNotifier  should be called at process ini-
     tialization time before the first call to Tcl_InitNotifier.


EXTERNAL EVENT LOOPS

     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 applica-
     tion.  In this case the notifier must arrange for the exter-
     nal  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 regular 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 easiest 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  ser-
     viced,  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 preceding para-
     graph,  which  will result in calls to Tcl_ServiceAll.  How-
     ever, in these cases it is undesirable to service events  in
     Tcl_ServiceAll.    Servicing  events  there  is  unnecessary

Tcl                     Last change: 8.1                       14

Notifier(3)          Tcl Library Procedures           Notifier(3)

     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 nor-
     mally services all pending events.  To  handle  this  situa-
     tion,  Tcl_DoOneEvent  sets  a  flag for Tcl_ServiceAll that
     causes it to return without servicing 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  service  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  procedure.   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_ServiceAll  will  behave
     normally.   Tcl_SetServiceMode returns the previous value of
     the service mode, which should be restored when  the  recur-
     sive  loop  exits.   Tcl_GetServiceMode  returns the current
     value of the service mode.


SEE ALSO

     Tcl_CreateFileHandler,   Tcl_DeleteFileHandler,   Tcl_Sleep,
     Tcl_DoOneEvent, Thread(3)


KEYWORDS

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

Tcl                     Last change: 8.1                       15


Man(1) output converted with man2html