naga.eventmachine
Class EventMachine

java.lang.Object
  extended by naga.eventmachine.EventMachine

public class EventMachine
extends java.lang.Object

EventMachine is a simple event service for driving asynchronous and delayed tasks together with the a Naga NIOService.

Creating and starting an event machine:

 EventMachine em = new EventMachine();
 // Start our event machine thread:
 em.start();
 
Delayed execution:
 em.executeLater(new Runnable() {
   public void run()
   {
      // Code here will execute after 1 second on the nio thread.
   }
 }, 1000);
 
Asynchronous execution, i.e. putting a task from another thread to be executed on the EventMachine thread.
 em.asyncExecute(new Runnable() {
   public void run()
   {
      // Code here will be executed on the nio thread.
   }
 });
 
It is possible to cancel scheduled tasks:
 // Schedule an event
 DelayedEvent event = em.executeLater(new Runnable()
   public void run()
   {
      // Code to run in 1 minute.
   }
 }, 60000);
 // Cancel the event before it is executed.
 event.cancel();
 

Author:
Christoffer Lerno

Constructor Summary
EventMachine()
          Creates a new EventMachine with an embedded NIOService.
 
Method Summary
 void asyncExecute(java.lang.Runnable runnable)
          Execute a runnable on the Event/NIO thread.
 DelayedEvent executeAt(java.lang.Runnable runnable, java.util.Date date)
          Execute a runnable on the Event/NIO thread after at a certain time.
 DelayedEvent executeLater(java.lang.Runnable runnable, long msDelay)
          Execute a runnable on the Event/NIO thread after a delay.
 NIOService getNIOService()
          Returns the NIOService used by this event service.
 ExceptionObserver getObserver()
          The current ExceptionObserver used by this service.
 java.util.Queue<naga.eventmachine.DelayedAction> getQueue()
          Return the current event service queue.
 int getQueueSize()
          Return the current queue size.
 void setObserver(ExceptionObserver observer)
          Sets the ExceptionObserver for this service.
 void start()
          Causes the event machine to start running on a separate thread together with the NIOService.
 void stop()
          Stops the event machine thread.
 long timeOfNextEvent()
          Returns the time when the next scheduled event will execute.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

EventMachine

public EventMachine()
             throws java.io.IOException
Creates a new EventMachine with an embedded NIOService.

Throws:
java.io.IOException - if we fail to set up the internal NIOService.
Method Detail

asyncExecute

public void asyncExecute(java.lang.Runnable runnable)
Execute a runnable on the Event/NIO thread.

This method is thread-safe.

Parameters:
runnable - the runnable to execute on the server thread as soon as possible,

executeLater

public DelayedEvent executeLater(java.lang.Runnable runnable,
                                 long msDelay)
Execute a runnable on the Event/NIO thread after a delay.

This is the primary way to execute delayed events, typically time-outs and similar behaviour.

This method is thread-safe.

Parameters:
runnable - the runnable to execute after the given delay.
msDelay - the delay until executing this runnable.
Returns:
the delayed event created to execute later. This can be used to cancel the event.

executeAt

public DelayedEvent executeAt(java.lang.Runnable runnable,
                              java.util.Date date)
Execute a runnable on the Event/NIO thread after at a certain time.

This is the primary way to execute scheduled events.

This method is thread-safe.

Parameters:
runnable - the runnable to execute at the given time.
date - the time date when this runnable should execute.
Returns:
the delayed event created to execute later. This can be used to cancel the event.

setObserver

public void setObserver(ExceptionObserver observer)
Sets the ExceptionObserver for this service.

The observer will receive all exceptions thrown by the underlying NIOService and by queued events.

This method is thread-safe.

Parameters:
observer - the observer to use, may not be null.
Throws:
java.lang.NullPointerException - if the observer is null.

timeOfNextEvent

public long timeOfNextEvent()
Returns the time when the next scheduled event will execute.

Returns:
a long representing the date of the next event, or Long.MAX_VALUE if no event is scheduled.

start

public void start()
Causes the event machine to start running on a separate thread together with the NIOService.

Note that the NIOService should not be called (using NIOService.selectNonBlocking() and related functions) on another thread if the EventMachine is used.


stop

public void stop()
Stops the event machine thread.


getObserver

public ExceptionObserver getObserver()
The current ExceptionObserver used by this service.

Will default to ExceptionObserver.DEFAULT if no observer was set.

Returns:
the current ExceptionObserver for this service.

getNIOService

public NIOService getNIOService()
Returns the NIOService used by this event service.

Returns:
the NIOService that this event service uses.

getQueue

public java.util.Queue<naga.eventmachine.DelayedAction> getQueue()
Return the current event service queue.

Returns:
a copy of the current queue.

getQueueSize

public int getQueueSize()
Return the current queue size.

Returns:
the number events in the event queue.