Shared state cache

Table of Contents

• What shared state means
  • Advantages of shared state
  • Disadvantages of shared state
• Enabling shared state
• Shared state and refreshing
  • Example:

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 of the entire bridge.

• 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.

• 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.

Shared state can be configured when the bridge is first constructed, either in getBridge() or in the constructor. Set sharedState to true to keep all resources connected to the bridge cache.

    hueplusplus::Bridge bridge = finder.getBridge(bridges[0], true);

    hueplusplus::Bridge bridge("192.168.2.102", 80, "<username>", handler, "", std::chrono::seconds(10), true);

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.

    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() 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.