Jacl Library Procedures - Notifier manual page

  CLASS
    tcl.lang.Notifier -- The event queue and notifier API.
  METHODS
    synchronized void deleteEvents(EventDeleter deleter)
    synchronized int doOneEvent(int flags)
    static synchronized Notifier getNotifierForThread(Thread thread)
    synchronized void preserve()
    synchronized void queueEvent(TclEvent event, int pos)
    synchronized void release()
  ARGUMENTS
  DESCRIPTION
    getNotifierForThread
    preserve, release
    queueEvent
      TCL.QUEUE_TAIL
      TCL.QUEUE_HEAD
      TCL.QUEUE_MARK
    deleteEvents
    doOneEvent
      TCL.WINDOW_EVENTS
      TCL.FILE_EVENTS
      TCL.TIMER_EVENTS
      TCL.IDLE_EVENTS
      TCL.ALL_EVENTS
      TCL.DONT_WAIT
  EQUIVALENT C FUNCTIONS
  SEE ALSO
  KEYWORDS

### CLASS

tcl.lang.Notifier -- The event queue and notifier API.

### METHODS

synchronized void deleteEvents(EventDeleter deleter)

synchronized int doOneEvent(int flags)

static synchronized Notifier getNotifierForThread(Thread thread)

synchronized void preserve()

synchronized void queueEvent(TclEvent event, int pos)

synchronized void release()

### ARGUMENTS

Thread thread ()
  The thread in which the Notifier should run.

EventDeleter deleter ()
  The EventDeleter determines which event in the event queue should be deleted.

TclEvent event ()
  The event to put into the event queue.

int pos ()
  The position at which the event should be queued.

int flags ()
  What types of events to service.

### DESCRIPTION

The Notifier is the lowest-level part of the Jacl event system. It is used by higher-level event sources such as file, JavaBean and timer events. The Notifier manages an event queue that holds TclEvent objects. The Jacl Notifier is designed to run in a multi-threaded environment. Each Notifier instance is associated with a primary thread. Any thread can queue (or dequeue) events using the queueEvent (or deleteEvents) call. However, only the primary thread may process events in the queue using the doOneEvent call. Attempts to call doOneEvent from a non-primary thread will cause a TclRuntimeError. This class doesn't have a public constructor and cannot be directly instantiated. You can get to it only through Notifier.getNotifierForThread or the getNotifier method of the Interp class.

getNotifierForThread
  This static method returns the Notifier instance whose primary thread is the given thread. If such an instance does not yet exist, it is created automatically.

preserve, release
  These two methods maintain a reference count to manage the lifetime of a Notifier and its corresponding event queue. When a Notifier is created inside the getNotifierForThread method, its reference count is zero. A call to preserve increments the reference count by one; a call to release decrements the reference count by one. When the reference count goes from one to zero, the Notifier is disposed -- its event queue is deleted and any left-over events in the queue will not be processed.

  If a Java module intends to use a Notifier returned by getNotifierForThread over one or more method calls, it should call preserve immediately after getNotifierForThread returns. The module should call relase when it no longer needs access to the notifier.

  NOTE: the notifier returned by interp.getNotifier will remain valid as long as the Interpreter is valid. Hence, if a module always access a notifier via calls to interp.getNotifier, it needs not use the notifier's preserve and release methods.

queueEvent
  This method puts the event into the event queue at the position specified by the pos argument. The pos argument may be one of the following:

  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.

deleteEvents
  This method provides a way to selectively delete events in the event queue. It calls deleter.deleteEvent for each event in the queue and deletes those for which deleter.deleteEvent returns 1. Events for which the deleter returns 0 are left in the queue.

doOneEvent
  This method is called in the context of the Notifier's primary thread to dispatch events in the event queue. If events are found in the event queue, the processEvent method of the first available event is called. If no event are in the queue, doOneEvent checks if there are idle handlers. If there are any, it invokes all of them and returns. Finally, if no events or idle callbacks have been found, then doOneEvent sleeps until an event occurs, calles processEvent the of the event and returns.

  If the flags argument to doOneEvent is non-zero, it restricts the kinds of events that will be processed by doOneEvent. Flags may be an OR-ed combination of any of the following bits:

  TCL.WINDOW_EVENTS
    Process window system events.

  TCL.FILE_EVENTS
    Process file events.

  TCL.TIMER_EVENTS
    Process timer events.

  TCL.IDLE_EVENTS
    Process idle callbacks.

  TCL.ALL_EVENTS
    Process all kinds of events: equivalent to OR-ing together all of the above flags or specifying none of them.

  TCL.DONT_WAIT
    Don't sleep: process only events that are ready at the time of the call.

    If any of the flags TCL.WINDOW_EVENTS, TCL.FILE_EVENTS, TCL.TIMER_EVENTS, or TCL.IDLE_EVENTS is set, then the only events that will be considered are those for which flags are set. Setting none of these flags is equivalent to the value TCL.ALL_EVENTS, which causes all event types to be processed. If an application has additional event sources then additional flag values may also be valid, depending on those event sources.

    The TCL.DONT_WAIT flag causes doOneEvent not to put the process to sleep: it will check for events but if none are found then it returns immediately with a return value of 0 to indicate that no work was done. doOneEvent will also return 0 without doing anything if the only alternative is to block forever (this can happen, for example, if flags is TCL.IDLE_EVENTS and there are no idle callbacks pending, or if no event handlers or timer handlers exist).

    doOneEvent may be invoked recursively. For example, it is possible to invoke doOneEvent recursively from an event handler called by doOneEvent. This sort of operation is useful in some modal situations, such as when a notification dialog has been popped up and an application wishes to wait for the user to click a button in the dialog before doing anything else.

### EQUIVALENT C FUNCTIONS

Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_DoOneEvent

### SEE ALSO

TclEvent, TimerHandler, IdleHandler, EventDeleter, Interp

### KEYWORDS

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

    Copyright © 1998 Sun Microsystems, Inc.
    Copyright © 1995-1997 Roger E. Critchlow Jr.