From e241361678d4247aaa85fe3223c3e91944fb7449 Mon Sep 17 00:00:00 2001 From: Leo Galambos Date: Thu, 28 Aug 2025 18:51:45 +0200 Subject: [PATCH] Update Programming Guide --- Programming-Guide.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/Programming-Guide.md b/Programming-Guide.md index 0278244..e08455e 100644 --- a/Programming-Guide.md +++ b/Programming-Guide.md @@ -143,9 +143,14 @@ Or clear everything: Ctx.INSTANCE.clear(); ``` -## Multiple Named Contexts +## Ephemeral Named Contexts -You can create and manage multiple independent contexts identified by names. +You can create multiple independent, **ephemeral contexts**, each identified by a unique name. +These contexts behave like isolated key–value stores: + +- They are created lazily on first access. +- They live only as long as you keep a reference to them. +- They are automatically deregistered once no strong references remain (via the garbage collector), or can be removed explicitly. ```java // Obtain or create named contexts @@ -172,15 +177,15 @@ Set contexts = Ctx.INSTANCE.contextNames(); System.out.println("Active contexts: " + contexts); ``` -Changes in one context do not affect others, allowing modular isolation of data. +Each context is fully isolated—changes in one do not affect any others—making them suitable for modular scoping (e.g., per-request, per-user, per-transaction). ## Best Practices -* Define your keys as constants to keep them consistent -* Register listeners in classes that depend on context changes -* Remove listeners when no longer needed (though weak references help) -* Use unique key names to avoid collisions within each context -* Use multiple contexts to logically separate unrelated data +* **Define keys as constants** – centralize Key definitions to avoid typos and ensure consistency across the codebase. +* **Scope listeners carefully** – register listeners only where reactive updates are needed; remove them when the owning component is disposed. (The framework uses weak references to help, but explicit cleanup is still good practice.) +* **Use descriptive, unique key names** – this prevents accidental collisions within a context and improves readability. +* **Separate concerns with multiple contexts** – create distinct contexts (e.g., "order", "user", "session") to isolate unrelated data and reduce coupling. +* **Treat named contexts as ephemeral** – hold onto a CtxInterface only for as long as you need it; once all strong references are gone, the context is automatically reclaimed by the garbage collector. ## Complete Example