Progress.

README.md

@@ -1,21 +1,64 @@
-# hdk grid api - holodeck foundation library
+# hdk grid api - hollow  foundation library
 
 This library provides the foundation for hdk, including core data structures, utilities, and interfaces that other components of the grid will build upon. It serves as the backbone of the system, enabling efficient management of holographic data and interactions.
 
-(TODO: Reword that last sentence)
-
 ## Shared Struct Wrapper
 
 The `SharedPtrWrapper` class is a reference-counted wrapper for shared pointers to structures. It provides a mechanism to manage the lifetime of shared resources while allowing for efficient access and caching of shared pointers. The wrapper ensures that shared pointers are properly managed and that resources are released when no longer needed, preventing memory leaks and ensuring efficient memory usage.
 
 The `SharedPtrWrapper` instances should be able to be used interchangeably with the underlying raw pointers in other C API calls, while still benefiting from the reference counting and caching mechanisms provided by the wrapper.
 
+## Primitive Wrapper
 
-## TODO Abstract Event Dispatching
+The `PrimitiveWrapper` class is a template wrapper for primitive types that provides a consistent interface for getting and setting properties. It allows for easy access to the underlying primitive value while also providing a layer of abstraction that can be useful for managing state and interactions within the grid system. The wrapper can be used to encapsulate primitive values and provide additional functionality, such as validation or transformation, while still allowing for direct access to the underlying value when needed.
 
-Things to consider:
+## Event Publishing System (EPS)
 
-- Define a point to register callbacks.
-- Support defining return type and arbitrary number of arguments for the callback.
-- Support, optionally, multiple callbacks for the same event.
-- Support disconnecting callbacks.
+`hdk::grid::eps::Conduit<Args...>` is a thread-safe, type-safe event dispatcher. Attach callbacks with `Attach(...)`; each subscription returns a move-only `Tap` handle. Fire the event with `Trigger(...)` or `operator()`. Callbacks run in attachment order from a snapshot taken under lock, so dispatch happens outside the lock and is safe against callbacks that detach or pause other taps.
+
+`Tap` supports `IsActive()`, `Detach()`, `Pause()`, `Resume()`, and `IsPaused()`. A tap becomes inactive after it is detached or if the underlying conduit is gone.
+
+`hdk::grid::eps::TapScope` groups multiple taps for bulk management. Add taps with `Add(...)` or `operator<<`, pause/resume them together with `PauseAll()` and `ResumeAll()`, and disconnect everything with `DetachAll()`. Its destructor also calls `DetachAll()`, so any taps still owned by the scope are disconnected automatically. `Clear()` only forgets the stored taps; the subscriptions stay active until detached elsewhere or the scope is destroyed.
+
+Example usage of `hdk::grid::eps::Conduit` and `Tap`:
+
+```cpp
+hdk::grid::eps::Conduit<int> changed;
+auto tap = changed.Attach([](int value) { /* handle value */ });
+changed.Trigger(42);
+tap.Detach();
+```
+
+Example usage of `hdk::grid::eps::TapScope` to manage multiple groups of taps:
+
+1. Somewhere else in the code base there are some conduits:
+2. Your class that needs to subscribe to some of these:
+3. Notice that we'vee got two `TapScope` instances, you can have as many as you want.
+4. Since the `TapScope` instances are members of `MyClass`, they will automatically detach all their taps when an instance of `MyClass` is destroyed, ensuring that there are no dangling subscriptions and that resources are properly cleaned up.
+
+
+```cpp
+// #1
+struct EventData { /* ... */ };
+hdk::grid::eps::Conduit<EventData*> event;
+hdk::grid::eps::Conduit<int> changed;
+hdk::grid::eps::Conduit<void> onMinimized, onRestored, onRender;
+
+// #2
+class MyClass {
+  protected:
+  // #3
+  hdk::grid::eps::TapScope genTaps, stateTaps;
+  public:
+  MyClass() {
+    // So let's say you normally do some things a lot of the time...
+    stateTaps << changed.Attach([this](int value) { /* handle value */ });
+    stateTaps << event.Attach([](EventData* data) { /* handle event */ });
+    stateTaps << onRender.Attach([]() { /* do render stuff */ });
+    // But sometimes you want to pause that stuff, but not everything else.
+    genTaps << onMinimized.Attach([this]() { stateTaps.PauseAll(); });
+    genTaps << onRestored.Attach([this]() { stateTaps.ResumeAll(); });
+    // Notice the genTaps group is always active and those handlers are used to control the other stateTaps group.
+  }
+}; // # 4
+```