From 8e6c4c131602ae8800c697c6d4a4ee169f3890be Mon Sep 17 00:00:00 2001
From: Jojo-1000 <33495614+Jojo-1000@users.noreply.github.com>
Date: Tue, 16 Mar 2021 19:03:05 +0100
Subject: [PATCH] Update documentation for shared state.

---
 README.md                       |  4 ++--
 doc/markdown/Getting_Started.md |  1 +
 doc/markdown/Mainpage.md        |  4 ++--
 doc/markdown/Shared_State.md    | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 59 insertions(+), 4 deletions(-)
 create mode 100644 doc/markdown/Shared_State.md

diff --git a/README.md b/README.md
index c63fc31..eae853c 100755
--- a/README.md
+++ b/README.md
@@ -8,10 +8,10 @@ A simple and easy to use library for Philips Hue Lights
 
 ## Features
 * find bridges with SSDP or set an ip manually
-* function to assign a username or set one manually
 * all common light functions (brightness, color, temperature)
 * extended alert() functions, which alert in a specific color (good for notifications)
-* creating custom sensors and reading sensor values
+* supports sensors, rules, groups, scenes and schedules
+* streaming with entertainment mode
 * [documented with doxygen](https://enwi.github.io/hueplusplus/)
 * tested with google test, google mock and gcov/lcov
 
diff --git a/doc/markdown/Getting_Started.md b/doc/markdown/Getting_Started.md
index f362f18..765b002 100644
--- a/doc/markdown/Getting_Started.md
+++ b/doc/markdown/Getting_Started.md
@@ -38,6 +38,7 @@ Here you will need to provide the ip address, the port number, a username and an
 auto handler = std::make_shared<hueplusplus::LinHttpHandler>();
 hueplusplus::Bridge bridge("192.168.2.102", 80, "<username>", handler);
 ```
+At this point you may want to decide whether to use a [shared state](@ref shared-state) cache model or keep the default settings.
 
 ### Controlling lights
 
diff --git a/doc/markdown/Mainpage.md b/doc/markdown/Mainpage.md
index 9c13457..eb6898d 100644
--- a/doc/markdown/Mainpage.md
+++ b/doc/markdown/Mainpage.md
@@ -3,10 +3,10 @@ A simple and easy to use library for Philips Hue Lights.
 
 ## Features
 * find bridges with SSDP or set an ip manually
-* function to assign a username or set one manually
 * all common light functions (brightness, color, temperature)
 * extended alert() functions, which alert in a specific color (good for notifications)
-* creating custom sensors and reading sensor values
+* supports sensors, rules, groups, scenes and schedules
+* streaming with entertainment mode
 * documented with doxygen
 * tested with google test, google mock and gcov/lcov
 
diff --git a/doc/markdown/Shared_State.md b/doc/markdown/Shared_State.md
new file mode 100644
index 0000000..fa12018
--- /dev/null
+++ b/doc/markdown/Shared_State.md
@@ -0,0 +1,54 @@
+# Shared state cache {#shared-state}
+
+## What shared state means
+There are two ways in which the API state (internally JSON) can be handled:
+1. Every resource instance holds its own cache of the state (default).
+2. All instances share the cache for the entire bridge.
+
+### Advantages of shared state
+* Different resources are always consistent on the library level.
+If one part of the code uses the light with id 1 and turns it off, 
+light 1 is also off when using a different variable to access it.
+* The number of requests can be reduced, because they can be bundled together on a higher cache level.
+
+### Disadvantages of shared state
+* Different objects are no longer thread safe, you cannot use **any** parts of the library 
+from multiple threads (without locking).
+* Changes are not transparent. For example, a `const Light` can suddenly change its name, because the
+name was changed somewhere else in the code.
+
+Because of these considerations, shared state is disabled by default.
+
+## Enabling shared state
+Shared state can be configured when the bridge is first constructed, either in [getBridge()](@ref hueplusplus::BridgeFinder::getBridge)
+or in the [constructor](@ref hueplusplus::Bridge::Bridge). Set `sharedState` to `true` to keep all resources
+connected to the bridge cache.
+```{.cpp}
+hueplusplus::Bridge bridge = finder.getBridge(bridges[0], true);
+```
+```{.cpp}
+hueplusplus::Bridge bridge("192.168.2.102", 80, "<username>", handler, std::chrono::seconds(10), true);
+```
+
+## Shared state and refreshing
+When shared cache is used, refreshes use a hierarchichal structure to determine how much should be requested from the bridge.
+Every level has its own last update time and refresh duration.
+First, it is checked whether the higher level is up to date and refresh everything if not.
+Otherwise, only the lowest necessary level is requested from the bridge to be more efficient.
+
+### Example:
+
+```{.cpp}
+bridge.setRefreshDuration(std::chrono::minutes(1));
+bridge.lights().setRefreshDuration(std::chrono::seconds(30));
+hueplusplus::Light light = bridge.lights().get(1);
+// ... wait some time
+bool on = light.isOn();
+```
+[isOn()](@ref hueplusplus::Light::isOn) is a non-const method (in this case). That means it will refresh the
+state if it is outdated. The default refresh time is inherited from `bridge.lights()`, so it is 30 seconds.
+After 30 seconds, the state of `light` *and* `bridge.lights()` is outdated. Therefore, the entire list of lights is
+updated at this point.
+
+After more than one minute, the bridge state is considered outdated. This means that `isOn()` causes an update of
+the entire bridge.
--
libgit2 0.21.4