From bfcbd5294dff5a6bd9acc4cab33813b2e32d7768 Mon Sep 17 00:00:00 2001
From: KeesCBakker <c.bakker@gmx.net>
Date: Sun, 29 May 2016 14:49:09 +0200
Subject: [PATCH] Async event execution test + documentation

---
 README.md                                     | 29 +++++++---------
 .../HowToDoAsynchronousEventDispatching.md    | 26 ++++++++++++++
 tests/StronglyTypesEvents-0.2.0.tests.ts      | 34 +++++++++++++++++++
 3 files changed, 73 insertions(+), 16 deletions(-)
 create mode 100644 documentation/HowToDoAsynchronousEventDispatching.md

diff --git a/README.md b/README.md
index 3f5f09cf..f2630bc4 100644
--- a/README.md
+++ b/README.md
@@ -9,14 +9,13 @@ This project will help you to add events, event handling en event dispatching to
 - <a href="documentation/HowToAddAnEventToAnInterface.md">How to add an event to an interface?</a>
 - <a href="documentation/HowToAddMultipleEventsToAClass.md">How to add multiple events to a class?</a>
 - <a href="documentation/HowToAddDynamicNamedEeventsToAClass.md">How to add dynamic named events to a class?</a>
+- <a href="documentation/HowToDoAsynchronousEventDispatching.md">How to do asynchronous event dispatching?</a>
 - <a href="documentation/OnEventsDispatchersAndLists.md">On events, dispatchers and lists (a general explanation of the system)</a>
 
 Code tells more than words, so let's give two examples:
-
 #### `IEventArgs<TSender, TArgs>` 
 These type of events are modelled after the .Net event handler system and uses a generic sender and a generic argument.
-
-````
+```
 class PulseGenerator {
 
     private _onPulsate: EventDispatcher<PulseGenerator, number> = new EventDispatcher<PulseGenerator, number>();
@@ -43,21 +42,19 @@ class PulseGenerator {
         }, 1000 / this.frequencyInHz);
     }
 }
-````
+```
 The events can be subscribed to like this: 
-````
+```
 let generator = new PulseGenerator(10);
 
 //subscribe on the onPulse event
 generator.onPulsate.subscribe((p, hz) => {
     alert('Peep!');
 });
-````
-
-#### `ISimpleEvent<TArgs>`
+```
+####`ISimpleEvent<TArgs>`
 Need something simpler? These type of events only use a generic argument.
-
-````
+```
 class ImageDownloader {
 
     private _ondownload: SimpleEventDispatcher<ImageDownloadArg> = new SimpleEventDispatcher();
@@ -84,10 +81,9 @@ class ImageDownloader {
         img.src = url;
     }
 }
-
-````
+```
 You can use events by subscribing onto the event:
-````
+```
 let downloader = new ImageDownloader();
 
 downloader.ondownload.subscribe((arg: ImageDownloadArg) => {
@@ -96,7 +92,7 @@ downloader.ondownload.subscribe((arg: ImageDownloadArg) => {
 });
 
 downloader.download('https://keestalkstech.com/wp-content/uploads/2016/05/hashing2-590x332.jpg');
-````
+```
 
 Check the <a href="documentation">documentation</a> or the <a href="examples">examples</a> for more information.
 
@@ -110,9 +106,10 @@ interfaces to make sure the base for both type of events are the same. The follo
 unsubscribe or dispatch events. Use the ToEvent() method to expose the event
 - `SimpleEventList<TSender, TArgs>` &ndash; Storage class for multiple events that are accessible by name. Events dispatchers are automatically created.
 - `SimpleEventHandlingBase<TSender, TArgs>` &ndash; Extends objects with simple event handling capabilities.
-- Added an `asEvent()` method to the dispatchers that will expose only the subsribe / unsubscribe methods. This will prevent
+- Added an `asEvent` method to the dispatchers that will expose only the subsribe / unsubscribe methods. This will prevent
 the `dispatch` method from being exposed through the events.
-
+- Added an `dispatchAsync` method to the dispatchers that will execute all subsriptions asynchronously. 
+<a href="documentation/HowToDoAsynchronousEventDispatching.md">Check this for more information</a>.
 
 #### Version 0.1
 Introducing the events - use a generic sender and a generic argument to dispatch events through your projects. The following 
diff --git a/documentation/HowToDoAsynchronousEventDispatching.md b/documentation/HowToDoAsynchronousEventDispatching.md
new file mode 100644
index 00000000..3dd7b204
--- /dev/null
+++ b/documentation/HowToDoAsynchronousEventDispatching.md
@@ -0,0 +1,26 @@
+#How to do asynchronous event dispatching?
+Normally event dispatching using a `EventDispatcher<TSender, TArgs>` or `SimpleEventDispatcher<TArgs>`
+is a synchronous process. This might not be desirable because a long event handler can hold up the rest of the
+handlers from being executed. That's why dispatchers can dispatch asynchronously by calling `dispatchAsync`.
+
+###Example
+Conside the following example:
+
+```
+QUnit.test('Testing simple event async dispatch', (assert) => {
+
+    let dispatcher = new SimpleEventDispatcher<number>();
+
+    let i = 0;
+
+    dispatcher.subscribe((a) => {
+        i = a;
+
+        assert.equal(i, 1);
+    });
+
+    dispatcher.dispatchAsync(1);
+
+    assert.equal(i, 0);
+});
+```
\ No newline at end of file
diff --git a/tests/StronglyTypesEvents-0.2.0.tests.ts b/tests/StronglyTypesEvents-0.2.0.tests.ts
index db102797..0edd9469 100644
--- a/tests/StronglyTypesEvents-0.2.0.tests.ts
+++ b/tests/StronglyTypesEvents-0.2.0.tests.ts
@@ -265,4 +265,38 @@ QUnit.test('Testing simple event dispatcher', (assert) => {
     });
 
     dispatcher.dispatch(a1);
+});
+
+QUnit.test('Testing event async dispatch', (assert) => {
+
+    let dispatcher = new EventDispatcher<any, number>();
+
+    let i = 0;
+
+    dispatcher.subscribe((s, a) => {
+        i = a;
+
+        assert.equal(i, 1);
+    });
+
+    dispatcher.dispatchAsync(null, 1);
+
+    assert.equal(i, 0);
+});
+
+QUnit.test('Testing simple event async dispatch', (assert) => {
+
+    let dispatcher = new SimpleEventDispatcher<number>();
+
+    let i = 0;
+
+    dispatcher.subscribe((a) => {
+        i = a;
+
+        assert.equal(i, 1);
+    });
+
+    dispatcher.dispatchAsync(1);
+
+    assert.equal(i, 0);
 });
\ No newline at end of file