From d59c6a52892c58dfa556dd2086e05d30ed193f70 Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Sun, 16 Oct 2022 21:15:29 +0200
Subject: [PATCH] Add docs for reflection API

---
 reflection.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)
 create mode 100644 reflection.md

diff --git a/reflection.md b/reflection.md
new file mode 100644
index 0000000..281e067
--- /dev/null
+++ b/reflection.md
@@ -0,0 +1,36 @@
+---
+title: Reflection
+permalink: /reflection
+layout: base
+---
+# Reflection
+
+> In computer science, reflective programming or reflection is the ability of a process to examine, introspect, and modify its own structure and behavior.
+> 
+> [Wikipedia](https://en.wikipedia.org/wiki/Reflective_programming)
+
+The event loop allows its own state to be inspected for various reasons, e.g. to build monitoring and observability tooling.
+
+All currently known event loop identifiers can be queried using `EventLoop::getIdentifiers()`.
+It'll return an array of string identifiers, which can be used for further inspection:
+
+ - `EventLoop::getType()` returns the callback type as an instance of `CallbackType`.
+ - `EventLoop::isEnabled()` returns whether the given callback is currently enabled.
+ - `EventLoop::isReferenced()` returns whether the given callback is currently referenced, i.e. keeps the event loop running.
+
+Let's say we want to monitor the number of enabled callbacks by type, then we can periodically collect these counts with the reflection API and report them to some kind of time series service:
+
+```php
+$stats = [];
+
+foreach (EventLoop::getIdentifiers() as $identifier) {
+    if (EventLoop::isEnabled($identifier)) {
+        $type = EventLoop::getType($identifier);
+    
+        $stats[$type->name] ??= 0;
+        $stats[$type->name]++;
+    }
+}
+
+// report $stats somewhere
+```
\ No newline at end of file