From 7c3cd017de8e59235f1199e499a72931cd7d4855 Mon Sep 17 00:00:00 2001
From: kske <kai@kske.dev>
Date: Sun, 21 Feb 2021 13:50:12 +0100
Subject: [PATCH] Add system events section to README

---
 README.md                                     | 32 +++++++++++++++++++
 .../java/dev/kske/eventbus/core/EventBus.java |  2 +-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0f839c5..01fd4c6 100644
--- a/README.md
+++ b/README.md
@@ -123,6 +123,38 @@ This applies to all event handlers that would have been executed after the one c
 Avoid cancelling events while using multiple event handlers with the same priority.
 As event handlers are ordered by priority, it is not defined which of them will be executed after the event has been consumed.
 
+## System Events
+
+To accommodate for special circumstances in an event distribution, system events have been introduced.
+At the moment, there are two system events, which are explained in this section.
+
+### Detecting Unhandled Events
+
+When an event is dispatched but not delivered to any handler, a dead event is dispatched that wraps the original event.
+You can declare a dead event handler to respond to this situation:
+
+```java
+private void onDeadEvent(DeadEvent deadEvent) { ... }
+```
+
+### Detecting Exceptions Thrown by Event Handlers
+
+When an event handler throws an exception, an exception event is dispatched that wraps the original event.
+A exception handler is declared as follows:
+
+```java
+private void onExceptionEvent(ExceptionEvent ExceptionEvent) { ... }
+```
+
+Both system events reference the event bus that caused them and a warning is logged if they are unhandled.
+
+### What About Endless Recursion Caused By Dead Events and Exception Events?
+
+As one might imagine, an unhandled dead event would theoretically lead to an endless recursion.
+The same applies when an exception event handler throws an exception.
+
+To avoid this, system events never cause system events and instead just issue a warning to the logger.
+
 ## Installation
 
 Event Bus is available in Maven Central.
diff --git a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
index f1e54b2..a719135 100644
--- a/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
+++ b/event-bus-core/src/main/java/dev/kske/eventbus/core/EventBus.java
@@ -89,7 +89,7 @@ public final class EventBus {
 						if (event instanceof DeadEvent || event instanceof ExceptionEvent)
 
 							// Warn about system event not being handled
-							logger.log(Level.WARNING, event + " not handled", e);
+							logger.log(Level.WARNING, event + " not handled due to exception", e);
 						else
 
 							// Dispatch exception event