tcl.lang
Class Notifier

java.lang.Object
  tcl.lang.Notifier

All Implemented Interfaces:

EventDeleter

public class Notifier
extends Object
implements EventDeleter

Implements the Jacl version of the Notifier class. The Notifier is the lowest-level part of the 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. Attepmts to call doOneEvent from a non-primary thread will cause a TclRuntimeError. This class does not have a public constructor and thus cannot be instantiated. The only way to for a Tcl extension to get an Notifier is to call Interp.getNotifier() (or Notifier.getNotifierForThread() ), which returns the Notifier for that interpreter (thread).

Method Summary

int	deleteEvent(TclEvent evt) Deprecated.
void	deleteEvents(EventDeleter deleter) Calls an EventDeleter for each event in the queue and deletes those for which deleter.deleteEvent() returns 1.
int	doOneEvent(int flags) Process a single event of some sort.
static Notifier	getNotifierForThread(Thread thread) Get the notifier for this thread, creating the Notifier, when necessary.
boolean	hasActiveInterps()
void	preserve() Increment the reference count of the notifier.
static void	processTclEvents(Notifier notifier)
void	queueEvent(TclEvent evt, int position) Insert an event into the event queue at one of three positions: the head, the tail, or before a floating marker.
void	release() Decrement the reference count of the notifier.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getNotifierForThread

public static Notifier getNotifierForThread(Thread thread)

Get the notifier for this thread, creating the Notifier, when necessary.

Parameters:

thread - the thread that owns this notifier

Returns:

The Notifier for this thread.

preserve

public void preserve()

Increment the reference count of the notifier. The notifier will be kept in the notifierTable (and alive) as long as its reference count is greater than zero.

release

public void release()

Decrement the reference count of the notifier. The notifier will be freed when its refCount goes from one to zero. Side effects: The notifier may be removed from the notifierTable when its refCount reaches zero.

queueEvent

public void queueEvent(TclEvent evt,
                       int position)

Insert an event into the event queue at one of three positions: the head, the tail, or before a floating marker. Events inserted before the marker will be processed in first-in-first-out order, but before any events inserted at the tail of the queue. Events inserted at the head of the queue will be processed in last-in-first-out order. Results: None. Side effects: If this method is invoked by a non-primary thread, the primaryThread of this Notifier will be notified about the new event.

Parameters:

evt - the event to be put on the queue

position - one of TCL.QUEUE_TAIL, TCL.QUEUE_HEAD or TCL.QUEUE_MARK.

deleteEvents

public void deleteEvents(EventDeleter deleter)

Calls an EventDeleter 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. This method includes code to handle the special case of the Notifier wanting to delete a single event after is has been serviced. This method is concurrent safe. Results: None. Side effects: Potentially removes one or more events from the event queue.

Parameters:

deleter - the deleter that checks whether an event should be removed

deleteEvent

@Deprecated
public int deleteEvent(TclEvent evt)

Deprecated.

This method is required to implement the EventDeleter interface It is not actually used though, see deleteEvents method for special casing of the deletion of a specific event.

Specified by:

deleteEvent in interface EventDeleter

Parameters:

evt - Event to test whether it should be removed

Returns:

1 means evt should be removed from the event queue. 0 otherwise.

doOneEvent

public int doOneEvent(int flags)

Process a single event of some sort. If there's no work to do, wait for an event to occur, then process it. May delay execution of process while waiting for an event, unless TCL.DONT_WAIT is set in the flags argument. Side effects: May delay execution of process while waiting for an event, unless TCL.DONT_WAIT is set in the flags argument. Event sources are invoked to check for and queue events. Event handlers may produce arbitrary side effects.

Parameters:

flags - Miscellaneous flag values: may be any combination of TCL.DONT_WAIT, TCL.WINDOW_EVENTS, TCL.FILE_EVENTS, TCL.TIMER_EVENTS, TCL.IDLE_EVENTS, or others defined by event sources.

Returns:

1 if the procedure actually found an event to process. If no processing occurred, then 0 is returned (this can happen if the TCL.DONT_WAIT flag is set or if there are no event handlers to wait for in the set specified by flags).

hasActiveInterps

public boolean hasActiveInterps()

processTclEvents

public static void processTclEvents(Notifier notifier)