Update documentation for shared state.

Jojo-1000 · Moritz Wirger
1 parent 72f9bfd1
Showing 4 changed files with 59 additions and 4 deletions
README.md
doc/markdown/Getting_Started.md
doc/markdown/Mainpage.md
doc/markdown/Shared_State.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
  
@@ -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
  
@@ -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
  
+# 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.