com.neeve.emx
Interface IEmxDispatcher

public interface IEmxDispatcher

Specifies the event dispatcher.

A dispatcher serves as the core event loop for an event driven program. The dispatcher exports methods to register interest in events and methods to drive the dispatcher event pump. Threads drive program execution by registering interest in events and driving the event pump. Upon invocation, the event pump waits for the registered events to get triggered at which point the triggered events are dispatched to associated event handlers. The event pump returns control to the caller when atleast one registered event was triggered and dispatched. Typically, unless the program execution is to be terminated, the caller almost immediately reinvokes the event pump to continue to dispatch triggered events. The repeated invocation of the event pump constitutes the program event loop.

A multi-threaded event driven program operates with multiple concurrently executing dispatchers. As noted in the threading section below, a dispatcher can be owned and operated by a single (owner) thread at a time. Therefore, in a multi-threaded program, at any point in time, each executing thread owns and operates its own dispatcher concurrently with the other executing threads. It is permissible to change thread-dispatcher ownerships during the lifecycle of the program. However, in a well designed multi-threaded event driven program based on the dispatcher, this rebalancing of thread-dispatcher ownnership should occur infrequently. In such a program architecture, inter thread communication is facilitated through the use of user events.

The registration of interest in an event is performed through the act of 'scheduling' an event. A user registers interest in an event by instantiating an event type specific event object object and handing it to the dispatcher for scheduling. The act of scheduling involves (1) waiting for the event specific condition to be triggered and (2) dispatching the provided event object to a specified event handler when the condition is triggered. From an event object lifecycle perspective, a registered event object waits in the dispatcher wait queue until the event condition is triggered. On trigger, the event object is moved to the dispatcher ready queue and dispatched in priority order. The return value from the event handler indicates whether the event continues to be scheduled by the dispatcher or not. A return value of true indicates that the user wishes for the event to be scheduled again. In this case, the event object is moved back to the wait queue. Otherwise, the event is discarded by the dispatcher. The event object also contains a flag to indicate whether repeat scheduling is permissible or not. In case the flag indicates that repeat scheduling is not possible, the return value from the event handler is ignored and the event always discarded after it is dispatched.

Since an event object is retained internally by the dispatcher in its wait queues, the event handler should not retain a reference to the event unless it is certain that the dispatcher has discarded its reference to the event (i.e. by returning false from the event handler and/or ensuring that the 'permit reschedule' flag is false in the event object).

The dispatcher supports three types of events. They are
- Network Ready Events
- Alarm Events
- User Events
There are four different types of network ready events. They are the 'connect ready' event, the 'accept ready' event, the 'read ready' event and the 'write ready' event. A separate scheduling/unscheduling method pair exists for each of these event types.

The scheduling of an 'accept ready' event means that the user wants to be notified when a specified EMX link server endpoint is ready to accept an incoming connection request. The user schedules such an event by instantiating an IEmxNwAcceptReadyEvent object and invoking the schedNwAcceptReadyEv(com.neeve.emx.IEmxNwAcceptReadyEvent) method. The instantiated event object contains the EMX link server endpoint of interest. A successful scheduling of the network event causes the dispatcher to place the event in the dispatcher wait queue where the event waits until there is an incoming link connection request waiting to be accepted via the provided server endpoint. The event is then moved from the wait queue to the ready queue from where it is dispatched to the user in priority order. The user can use the unschedNwAcceptReadyEv(com.neeve.emx.IEmxNwAcceptReadyEvent) method to unschedule a previously scheduled 'accept ready' event i.e. remove the event from the dispatcher's scheduling queues before it is dispatched to the user. 'Accept ready' event scheduling and unscheduling can only be done by the dispatcher owner thread.

The scheduling of a 'connect ready' event means that the user wants to be notified when a specified EMX link client endpoint is ready to complete a previously initiated connection request. The user schedules such an event by instantiating an IEmxNwConnectReadyEvent object and invoking the schedNwConnectReadyEv(com.neeve.emx.IEmxNwConnectReadyEvent) method. The instantiated event object contains the EMX link client endpoint of interest. A successful scheduling of the network event causes the dispatcher to place the event in the dispatcher wait queue where the event waits until the connection request is ready to be completed. The event is then moved from the wait queue to the ready queue from where it is dispatched to the user in priority order. The user can use the unschedNwConnectReadyEv(com.neeve.emx.IEmxNwConnectReadyEvent) method to unschedule a previously scheduled 'connect ready' event i.e. remove the event from the dispatcher's scheduling queues before it is dispatched to the user. 'Connect ready' event scheduling and unscheduling can only be done by the dispatcher owner thread.

The scheduling of a 'read ready' event means that the user wants to be notified when there is data ready to be read through a specified EMX link peer endpoint. The user schedules such an event by instantiating an IEmxNwReadReadyEvent object and invoking the schedNwReadReadyEv(com.neeve.emx.IEmxNwReadReadyEvent) method. The instantiated event object contains the EMX link peer endpoint of interest. A successful scheduling of the network event causes the dispatcher to place the event in the dispatcher wait queue where the event waits until the data is ready to be read through the client endpoint. The event is then moved from the wait queue to the ready queue from where it is dispatched to the user in priority order. The user can use the unschedNwReadReadyEv(com.neeve.emx.IEmxNwReadReadyEvent) method to unschedule a previously scheduled 'read ready' event i.e. remove the event from the dispatcher's scheduling queues before it is dispatched to the user. 'Read ready' event scheduling and unscheduling can only be done by the dispatcher owner thread.

The scheduling of a 'write ready' event means that the user wants to be notified when a specified EMX link peer endpoint is ready for data to be written through it. The user schedules such an event by instantiating an IEmxNwWriteReadyEvent object and invoking the schedNwWriteReadyEv(com.neeve.emx.IEmxNwWriteReadyEvent) method. The instantiated event object contains the EMX link peer endpoint of interest. A successful scheduling of the network event causes the dispatcher to place the event in the dispatcher wait queue where the event waits until the the client endpoint is ready for data to be written through it. The event is then moved from the wait queue to the ready queue from where it is dispatched to the user in priority order. The user can use the unschedNwWriteReadyEv(com.neeve.emx.IEmxNwWriteReadyEvent) method to unschedule a previously scheduled 'write ready' event i.e. remove the event from the dispatcher's scheduling queues before it is dispatched to the user. 'Write ready' event scheduling and unscheduling can only be done by the dispatcher owner thread.

The request to schedule an alarm event means that the user want to be notified after a specified time interval. The user schedules an alarm event by instantiating an IEmxAlarmEvent and invoking the schedAlarmEv(com.neeve.emx.IEmxAlarmEvent) method. The instantiate event object contains the timeout interval upon expiry of which the user needs to be notified. A successful scheduling of an alarm event causes the event to be placed in the wait queue where the event waits for the specified time interval. After expiry of the interval, the event is moved to the ready queue from where it is dispatched in priority order. The user can use the unschedAlarmEv(com.neeve.emx.IEmxAlarmEvent) method to cancel an alarm i.e. remove the alarm event from the scheduler queues. The resetAlarmEv(com.neeve.emx.IEmxAlarmEvent, long) is used to reset the alarm base time (the base time + interval = dispatch time). The scheduling and unscheduling of alarm events can only be done by the dispatcher owner thread.

The request to schedule a user event means that the user just wants to place the event in the dispatcher ready queue. User events, as opposed to alarm and network events, do not have a triggering condition. User events are ready for dispatch immediately when scheduled and, once again opposed to alarm and network events, can be scheduled by a thread different from the owner thread of the dispatcher in which the event is being scheduled. Events scheduled by the owner thread of the dispatcher in which they are scheduled is a technique typically used to defer the processing of a task (since the act of scheduling an event puts the event behind all events of higher or equal priority in the dispatchers ready queue). Scheduling events in dispatchers owned by a different thread is a mechanism used for inter thread communication.

Threading:

An EMX dispatcher is not safe for concurrent access by multiple threads except the scheduling of user events which can occur concurrently with other methods. At any point in time, a dispatcher object is owned by a thread. The thread that creates the dispatcher starts off as the dispatcher owner. A thread can take ownership of the dispatcher via the setOwner(int) method at any point during the lifetime of the dispatcher. However, the dispatcher needs to be in a particular state for ownership to be transferred. Refer to setOwner(int) for more information on permissible states in which thread ownership can be changed. Most dispatcher methods apart from the method used to schedule user events permit invocation only by the owner thread. Refer to the method documentation for more information on which threads are permitted to invoke which methods.

Nested Class Summary

static class

IEmxDispatcher.Params Specifies dispatcher operating parameters.

Field Summary

static int

FLAG_TAG_TO_OWNER Instruct a dispatcher to tag the owner thread with the owned dispatcher.

Method Summary

void	close(boolean flush) Close the dispatcher.
void	flush() Flush the dispatcher ready queue.
Object	getAttachment() Get the object currently attached to the dispatcher.
String	getName() Get the dispatcher name.
Thread	getOwner() Get the current owner of the dispatcher.
IEmxDispatcher.Params	getParams() Get the dispatcher parameters object.
int	getReadyEvCount() Get the number of events in the dispatcher ready queue.
IEmxDispatcherStats	getStats() Get the dispatcher statistics object.
boolean	getThreaded() Get whether the dispatcher is operating in a multi-threaded mode.
int	getWaitEvCount() Get the number of events in the dispatcher wait queue.
void	resetAlarmEv(IEmxAlarmEvent event, long lastDispatchTime) Reset a scheduled alarm event.
int	run(int timeout) The dispatcher event pump.
Object	run(int timeout, IEmxDispatcherRunCompletionChecker completionChecker) Drives the dispatcher until user deems complete or timeout.
void	schedAlarmEv(IEmxAlarmEvent event) Schedule an alarm event for dispatch.
void	schedEv(IEmxEvent event) Schedule an event for dispatch.
void	schedNwAcceptReadyEv(IEmxNwAcceptReadyEvent event) Schedule an 'accept ready' event for dispatch.
void	schedNwConnectReadyEv(IEmxNwConnectReadyEvent event) Schedule a 'connect ready' event for dispatch.
void	schedNwReadReadyEv(IEmxNwReadReadyEvent event) Schedule an 'read ready' event for dispatch.
void	schedNwWriteReadyEv(IEmxNwWriteReadyEvent event) Schedule an 'write ready' event for dispatch.
void	schedUserEv(IEmxUserEvent event) Schedule a user event for dispatch.
void	setAttachment(Object object) Attach an opaque object to the dispatcher.
void	setOwner() Acquire ownership of the dispatcher.
void	setOwner(int flags) Acquire ownership of the dispatcher.
void	unschedAlarmEv(IEmxAlarmEvent event) Cancel a scheduled alarm event.
void	unschedEv(IEmxEvent event) Cancel a scheduled event.
void	unschedNwAcceptReadyEv(IEmxNwAcceptReadyEvent event) Cancel a scheduled 'accept ready' event.
void	unschedNwConnectReadyEv(IEmxNwConnectReadyEvent event) Cancel a scheduled 'connect ready' event.
void	unschedNwReadReadyEv(IEmxNwReadReadyEvent event) Cancel a scheduled 'read ready' event.
void	unschedNwWriteReadyEv(IEmxNwWriteReadyEvent event) Cancel a scheduled 'write ready' event.

Field Detail

FLAG_TAG_TO_OWNER

static final int FLAG_TAG_TO_OWNER

Instruct a dispatcher to tag the owner thread with the owned dispatcher.

This flag is used by the setOwner(int) method to determine whether to set owned dispatcher in the dispatcher thread local variable. This enables getting the dispatcher from a thread from anywhere in a program.

See Also:

Constant Field Values

Method Detail

getName

String getName()

Get the dispatcher name.

Returns:

Returns the name of the dispatcher.

A dispatcher name is used to to identify a dispatcher during tracing and debugging. The dispatcher name is srt during dispatcher creation and cannot be changed during the lifetime of the dispatcher.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

setOwner

void setOwner(int flags)

Acquire ownership of the dispatcher.

Parameters:

flags - Flags used to qualify the ownership acquisition operation. The following flags are permissible for use here:
- FLAG_TAG_TO_OWNER

This method transfers ownership of the dispatcher to the calling thread. Optionally, if the FLAG_TAG_TO_OWNER flag is specified, the method also sets the EmxThread.dispatcher thread local variable with the owned dispatcher.

Threading:

This method can be invoked by any thread but cannot be invoked concurrently with any other method in this class i.e. the user is responsible for ensuring that no thread is executing any method in this class while ownership of the dispatcher is being transferred. The behaviour of this method in case any other method is being invoked concurrently is undefined.

setOwner

void setOwner()

Acquire ownership of the dispatcher.

This method invokes the following:

setOwner(FLAG_TAG_TO_OWNER)

getOwner

Thread getOwner()

Get the current owner of the dispatcher.

Returns:

Returns the current owner of the dispatcher.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

getThreaded

boolean getThreaded()

Get whether the dispatcher is operating in a multi-threaded mode.

Returns:

Returns whether the dispatcher is operating in a multi-threaded mode. The return value from this method will always be equal to the threaded parameter in the parameters object returned by the getParams() method.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

getParams

IEmxDispatcher.Params getParams()

Get the dispatcher parameters object.

Returns:

Returns the dispatcher parameters object

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

getStats

IEmxDispatcherStats getStats()

Get the dispatcher statistics object.

Returns:

Returns the dispatcher statistics object

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

setAttachment

void setAttachment(Object object)

Attach an opaque object to the dispatcher.

This method replaces the current attachment with the provided object.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

getAttachment

Object getAttachment()

Get the object currently attached to the dispatcher.

Returns:

Returns the current attachment.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

getWaitEvCount

int getWaitEvCount()
                   throws EEmxNotOwnerException

Get the number of events in the dispatcher wait queue.

Returns:

Returns the number of events in the dispatcher wait queue.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

This method returns the number of events in the dispatcher wait queue. Events in the wait queue are awaiting for an appropriate event to be triggered before they are moved to the dispatcher ready queue for dispatch.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

getReadyEvCount

int getReadyEvCount()
                    throws EEmxNotOwnerException

Get the number of events in the dispatcher ready queue.

Returns:

Returns the number of events in the dispatcher ready queue.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

This method returns the number of events in the dispatcher ready queue pending dispatch.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedUserEv

void schedUserEv(IEmxUserEvent event)
                 throws EEmxAlreadyScheduledException

Schedule a user event for dispatch.

Parameters:

event - The user event to be scheduled

Throws:

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules a user event for dispatch. The event is placed directly in the dispatcher ready queue and is ready for dispatch.

Threading:

This method is safe for concurrent access by multiple threads and can be executed concurrently with any other method in the class.

schedAlarmEv

void schedAlarmEv(IEmxAlarmEvent event)
                  throws EEmxNotOwnerException,
                         EEmxAlreadyScheduledException

Schedule an alarm event for dispatch.

Parameters:

event - The alarm event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules an alarm event for dispatch. The event is placed into the dispatcher wait queue and is moved to ready queue for dispatch upon expiry of the specified interval.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

resetAlarmEv

void resetAlarmEv(IEmxAlarmEvent event,
                  long lastDispatchTime)
                  throws EEmxNotOwnerException,
                         EEmxNotScheduledException

Reset a scheduled alarm event.

Parameters:

event - The alarm event to be reset.

lastDispatchTime - Specifies the time to which to reset the alarm event's bsae time (base time + interval = dispatch time). A value of 0 causes the alarm to be reset using the current time.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method resets a scheduled alarm event. Resetting an alarm event causes the dispatcher to set the alarm event's base time to the specified time i.e. the event will now be dispatched at a time equal to the specified last dispatch time plus the alarm interval.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedAlarmEv

void unschedAlarmEv(IEmxAlarmEvent event)
                    throws EEmxNotOwnerException,
                           EEmxNotScheduledException

Cancel a scheduled alarm event.

Parameters:

event - The alarm event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method removes a previously scheduled alarm event from the dispatcher's scheduling queues. A successful return from this method guarantees that the dispatcher releases all its references to the cancelled alarm event and the event will not be subsequently dispatched to the user.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedNwAcceptReadyEv

void schedNwAcceptReadyEv(IEmxNwAcceptReadyEvent event)
                          throws EEmxNotOwnerException,
                                 EEmxAlreadyScheduledException

Schedule an 'accept ready' event for dispatch.

Parameters:

event - The 'accept ready' event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules an 'accept ready' event for dispatch. The event is placed into the dispatcher wait queue and is moved to ready queue for dispatch when the EMX link server endpoint contained in the event object is ready to accept an incoming connection request.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedNwAcceptReadyEv

void unschedNwAcceptReadyEv(IEmxNwAcceptReadyEvent event)
                            throws EEmxNotOwnerException,
                                   EEmxNotScheduledException

Cancel a scheduled 'accept ready' event.

Parameters:

event - The 'accept ready' event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method removes a previously scheduled 'accept ready' event from the dispatcher's scheduling queues. A successful return from this method guarantees that the dispatcher releases all its references to the the cancelled network event and the event will not be subsequently dispatched to the user.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedNwConnectReadyEv

void schedNwConnectReadyEv(IEmxNwConnectReadyEvent event)
                           throws EEmxNotOwnerException,
                                  EEmxAlreadyScheduledException

Schedule a 'connect ready' event for dispatch.

Parameters:

event - The 'connect ready' event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules a 'connect ready' event for dispatch. The event is placed into the dispatcher wait queue and is moved to ready queue for dispatch when the EMX link client endpoint contained in the event object is ready to complete the connect operation.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedNwConnectReadyEv

void unschedNwConnectReadyEv(IEmxNwConnectReadyEvent event)
                             throws EEmxNotOwnerException,
                                    EEmxNotScheduledException

Cancel a scheduled 'connect ready' event.

Parameters:

event - The 'connect ready' event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method removes a previously scheduled 'connect ready' event from the dispatcher's scheduling queues. A successful return from this method guarantees that the dispatcher releases all its references to the the cancelled network event and the event will not be subsequently dispatched to the user.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedNwReadReadyEv

void schedNwReadReadyEv(IEmxNwReadReadyEvent event)
                        throws EEmxNotOwnerException,
                               EEmxAlreadyScheduledException

Schedule an 'read ready' event for dispatch.

Parameters:

event - The 'read ready' event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules an 'read ready' event for dispatch. The event is placed into the dispatcher wait queue and is moved to ready queue for dispatch when the EMX link peer endpoint contained in the event object is ready to read an incoming data.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedNwReadReadyEv

void unschedNwReadReadyEv(IEmxNwReadReadyEvent event)
                          throws EEmxNotOwnerException,
                                 EEmxNotScheduledException

Cancel a scheduled 'read ready' event.

Parameters:

event - The 'read ready' event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method removes a previously scheduled 'read ready' event from the dispatcher's scheduling queues. A successful return from this method guarantees that the dispatcher releases all its references to the the cancelled network event and the event will not be subsequently dispatched to the user.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedNwWriteReadyEv

void schedNwWriteReadyEv(IEmxNwWriteReadyEvent event)
                         throws EEmxNotOwnerException,
                                EEmxAlreadyScheduledException

Schedule an 'write ready' event for dispatch.

Parameters:

event - The 'write ready' event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

This method schedules an 'write ready' event for dispatch. The event is placed into the dispatcher wait queue and is moved to ready queue for dispatch when the EMX link peer endpoint contained in the event object is ready to write outgoing data.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedNwWriteReadyEv

void unschedNwWriteReadyEv(IEmxNwWriteReadyEvent event)
                           throws EEmxNotOwnerException,
                                  EEmxNotScheduledException

Cancel a scheduled 'write ready' event.

Parameters:

event - The 'write ready' event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

This method removes a previously scheduled 'write ready' event from the dispatcher's scheduling queues. A successful return from this method guarantees that the dispatcher releases all its references to the the cancelled network event and the event will not be subsequently dispatched to the user.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

schedEv

void schedEv(IEmxEvent event)
             throws EEmxNotOwnerException,
                    EEmxAlreadyScheduledException

Schedule an event for dispatch.

Parameters:

event - The event to be scheduled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxAlreadyScheduledException - Thrown in case the event is currently scheduled with a dispatcher.

IllegalArgumentException - Thrown in case the event type is not recognized by the dispatcher.

This method is a convenience method to schedule an event for dispatch. The method checks the event type and incokes the type specific schedule method.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

unschedEv

void unschedEv(IEmxEvent event)
               throws EEmxNotOwnerException,
                      EEmxNotScheduledException

Cancel a scheduled event.

Parameters:

event - The event to be cancelled.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxNotScheduledException - Thrown in case the event is not currently scheduled with the dispatcher.

IllegalArgumentException - Thrown in case the event type is not recognized by the dispatcher.

This method is a convenience method to cancel a scheduled event. The method checks the event type and incokes the type specific unschedule method.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

run

int run(int timeout)
        throws EEmxNotOwnerException

The dispatcher event pump.

Parameters:

timeout - Specifies the maximum time in milliseconds to wait for events to arrive for dispatch. A value < 0 indicates an indefinite wait.

Returns:

Returns the number of events dispatched in this invocation. A value of 0 is returned if an only if no event was ready for dispatch within the specified timeout period.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

This method dispatches events present in the dispatcher ready queue. In case the ready queue is empty, the method sleeps and wait for the specified timeout for an event to arrive in the ready queue. The method will return when atleast one event is dispatched by the method or the timeout expired before any event arrived in the ready queue.

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

run

Object run(int timeout,
           IEmxDispatcherRunCompletionChecker completionChecker)
           throws EEmxNotOwnerException,
                  EEmxTimeoutException,
                  EEmxException

Drives the dispatcher until user deems complete or timeout.

Parameters:

timeout - Specifies the maximum time in milliseconds to run the dispatcher. A value < 0 indicates an indefinite run.

completionChecker - The object that this method will consult to determine whether the run has completed or not. This parameter can be null in which case the method will return only on timeout or error.

Returns:

Returns the object returned by the completion checker.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

EEmxTimeoutException - Thrown if the timeout occurred before the completion checker indicated completion.

ELnkException - Thrown in case an error occurs during the running of the dispatcher or the completion checker threw an exception on completion.

This method runs the dispatcher dispatching events until the specified completion checker reports that the run has completed, the timeout specified expires or an error occurs. Essentially, this method invokes run(int) using a diminishing timeout and querying the completion checker for completion after each invocation to run(int)

EEmxException

Threading:

This method can only be invoked by the dispatcher owner thread and can be invoked concurrently with other methods that allow access by non-owner threads.

flush

void flush()
           throws EEmxNotOwnerException

Flush the dispatcher ready queue.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner.

This method dispatches any events pending dispatch in the dispatcher ready queue.

Threading:

This method can only be invoked by the dispatcher owner thread amd cannot be invoked concurrently with any other method in this class.

close

void close(boolean flush)
           throws EEmxNotOwnerException,
                  EEmxException

Close the dispatcher.

Throws:

EEmxNotOwnerException - Thrown in case this method is invoked by a thread that is not the dispatcher owner and a flush is requested. The method can be closed by the non-owner thread in case a flush is not requested.

EEmxException - Thrown if an error occurred while closing internal dispatcher resources.

This method closes the dispatcher. This method should be invoked by a user when it is done working with the dispatcher. This this method will invoke flush() (if requested) to dispatch any remaining events in the ready queue, automatically cancel any events pending in the wait queues and then release all internal dispatcher resources.

Threading:

This method can only be invoked by the dispatcher owner thread amd cannot be invoked concurrently with any other method in this class.