EventMachine (Naga API)
Date: 2016-06-28

naga.eventmachine

## Class EventMachine

- java.lang.Object
- - 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

    Constructors
    Constructor and Description
    `EventMachine()` Creates a new EventMachine with an embedded NIOService.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `java.util.Queue<DelayedEvent>` | `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` | `shutdown()` Stops the event machine and closes the underlying NIO service, it is not possible to restart the event machine after shutdown.
    `void` | `start()` Causes the event machine to start running on a separate thread together with the NIOService.
    `void` | `stop()` Stops the event machine thread, it may be restarted using start()
    `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, null will cause exceptions to log to stderr

    - #### 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, it may be restarted using start()

    - #### shutdown

          public void shutdown()

      Stops the event machine and closes the underlying NIO service, it is not possible to restart the event machine after shutdown.

    - #### 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<DelayedEvent> 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.