Asynchronous Events

Discussion in 'Bukkit Preview' started by Wolvereness, Jun 13, 2012.

  1. Offline

    Wolvereness Bukkit Team Member

    In the latest developer builds, there is a new concept called Asynchronous Events.

    • Asynchronous Events does NOT mean all of your listeners are now run on new threads.
    • Calling an Asynchronous Event executes the event from the calling thread. When you call that method, your execution does not continue until all listeners are done.
    • No Bukkit event is declared Asynchronous unless specifically denoted as such. On a similar note, we will only add new Asynchronous Events to places in code where there is a use-case and minimal diff.
    • As of implementation, the only Asynchronous Event is a new AsyncPreLoginEvent.
    • When you listen for an Asynchronous Event, your listener may be executed multiple times, simultaneously, and in any order*. You should keep this in mind when you write a listener for an Asynchronous Event. *A specific event will still maintain event listener priorities, but if two events are fired, the second one fired may finish first.
    • You cannot fire an asynchronous event inside of a normal event's listener.
    • You cannot fire an asynchronous event inside of a synchronized task, or any block of code from normal execution.
    • You may fire normal events (it's preferred you do this in a Future task though) from inside an asynchronous event.
    • Asynchronous Events are designed to let you 'block' execution. A good example of this would be using the second thread to query a server and wait for a response. The thread that called the event will wait until the listener is done, hence why it is illegal to call an Asynchronous Event from the primary thread.
    • Custom events are not obligated to always be synchronous or asynchronous. Because it's in the constructor, it may be declared at object creation. Once created, the specific event may not be changed.
    • Similarly, all Bukkit events are explicitly declared as either synchronous or asynchronous (you cannot override this for a Bukkit event).
    • New listeners to an event are ignored until the next time that event is fired.
    • When an event is called asynchronously, it does not get added to the plugin timing system.
    • Asynchronous Events are not designed to increase performance, but rather give better state management for operations that are already done on secondary threads.
    • You should not start a new thread just to call an asynchronous event. Thread creation is not trivial, and can will degrade performance.

Share This Page