From 715ae44ff92381ef6df8a9971c0639fd5cc255bd Mon Sep 17 00:00:00 2001
From: graemerocher <graeme.rocher@gmail.com>
Date: Wed, 11 Mar 2015 13:00:11 +0100
Subject: [PATCH] Documentation on events

---
 src/en/guide/async/events.gdoc           | 17 +++++++++++++++++
 src/en/guide/async/events/consuming.gdoc | 11 +++++++++++
 src/en/guide/async/events/notifying.gdoc |  8 ++++++++
 src/en/guide/toc.yml                     |  4 ++++
 4 files changed, 40 insertions(+)
 create mode 100644 src/en/guide/async/events.gdoc
 create mode 100644 src/en/guide/async/events/consuming.gdoc
 create mode 100644 src/en/guide/async/events/notifying.gdoc

diff --git a/src/en/guide/async/events.gdoc b/src/en/guide/async/events.gdoc
new file mode 100644
index 00000000000..47b9f6b9aac
--- /dev/null
+++ b/src/en/guide/async/events.gdoc
@@ -0,0 +1,17 @@
+Grails 3.0 introduces a new Events API based on [Reactor|https://github.com/reactor/reactor].
+
+All services and controllers in Grails 3.0 implement the [Events|api:grails.events.Events] trait.
+
+The @Events@ trait allows the ability to consume and publish events that are handled by Reactor.
+
+The default Reactor configuration utilises a thread pool backed event bus. You can however configure Reactor within @application.yml@, for example:
+
+{code}
+reactor
+    dispatchers:
+        default: myExecutor
+        myExecutor:
+            type: threadPoolExecutor
+            size: 5
+            backlog: 2048
+{code}
diff --git a/src/en/guide/async/events/consuming.gdoc b/src/en/guide/async/events/consuming.gdoc
new file mode 100644
index 00000000000..6d759e0f87c
--- /dev/null
+++ b/src/en/guide/async/events/consuming.gdoc
@@ -0,0 +1,11 @@
+There are several ways to consume an event. As mentioned previously services and controllers implement the [Events|api:grails.events.Events] trait.
+
+The @Events@ trait provides several methods to register event consumers. For example:
+
+{code}
+on("myEvent") {
+    println "Event fired!"
+}
+{code}
+
+Note that if you wish a class (other than a controller or service) to be an event consumer you simply have to implement the @Events@ trait and ensure the class is registered as a Spring bean.
diff --git a/src/en/guide/async/events/notifying.gdoc b/src/en/guide/async/events/notifying.gdoc
new file mode 100644
index 00000000000..7dc5575802a
--- /dev/null
+++ b/src/en/guide/async/events/notifying.gdoc
@@ -0,0 +1,8 @@
+The @Events@ trait also provides methods for notifying of events. For example:
+
+{code}
+notify "myEvent", "myData"
+sendAndReceive "myEvent", "myData", {
+    println "Got response!"
+}
+{code}
diff --git a/src/en/guide/toc.yml b/src/en/guide/toc.yml
index 900d6dd92f8..fd1eef8bb06 100644
--- a/src/en/guide/toc.yml
+++ b/src/en/guide/toc.yml
@@ -218,6 +218,10 @@ webServices:
 async:
   title: Asynchronous Programming
   promises: Promises
+  events:
+      title: Events
+      consuming: Consuming Events
+      notifying: Event Notification
   asyncGorm: Asynchronous GORM
   asyncRequests: Asynchronous Request Handling
   asyncServletApi: Servlet 3.0 Async