environment.hpp

Go to the documentation of this file.

#pragma once

 
#include <atomic>
#include <cstdint>
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <vector>
 
namespace pulp::platform {

enum class ColorScheme : uint8_t {
    light,
    dark,
    unknown,
};

enum class LifecycleState : uint8_t {
    foreground,
    inactive,
    background,
    unknown,
};

enum class Orientation : uint8_t {
    portrait,
    portrait_upside_down,
    landscape_left,
    landscape_right,
    flat,
    unknown,
};

enum class MemoryPressure : uint8_t {
    normal,
    moderate,
    critical,
};

struct SafeAreaInsets {
    float top    = 0.0f;
    float bottom = 0.0f;
    float left   = 0.0f;
    float right  = 0.0f;
 
    bool is_zero() const noexcept {
        return top == 0.0f && bottom == 0.0f && left == 0.0f && right == 0.0f;
    }
};

struct KeyboardInset {
    float bottom = 0.0f;
    float animation_duration = 0.0f;
};

struct DisplayInfo {
    float width        = 0.0f;
    float height       = 0.0f;
    int   physical_width  = 0;
    int   physical_height = 0;
    float scale         = 1.0f;
    float refresh_hz    = 0.0f;
    std::string name;
};

struct EnvironmentChange {
    bool display          : 1;
    bool safe_area        : 1;
    bool keyboard         : 1;
    bool orientation      : 1;
    bool color_scheme     : 1;
    bool lifecycle        : 1;
    bool memory_pressure  : 1;
 
    EnvironmentChange() noexcept
        : display(false), safe_area(false), keyboard(false),
          orientation(false), color_scheme(false), lifecycle(false),
          memory_pressure(false) {}
 
    bool any() const noexcept {
        return display || safe_area || keyboard || orientation
            || color_scheme || lifecycle || memory_pressure;
    }
};

struct EnvironmentState {
    DisplayInfo     display;
    SafeAreaInsets  safe_area;
    KeyboardInset   keyboard;
    Orientation     orientation     = Orientation::unknown;
    ColorScheme     color_scheme    = ColorScheme::unknown;
    LifecycleState  lifecycle       = LifecycleState::unknown;
    MemoryPressure  memory_pressure = MemoryPressure::normal;
};

class Environment {
public:
    using Listener = std::function<void(const EnvironmentState&,
                                        EnvironmentChange)>;

    class Token {
    public:
        Token() = default;
        ~Token() { reset(); }
        Token(Token&& other) noexcept;
        Token& operator=(Token&& other) noexcept;
        Token(const Token&) = delete;
        Token& operator=(const Token&) = delete;
        void reset() noexcept;
        bool valid() const noexcept { return id_ != 0; }
    private:
        friend class Environment;
        Token(uint64_t id) : id_(id) {}
        uint64_t id_ = 0;
    };

    static Environment& instance();

    EnvironmentState snapshot() const;

    Token subscribe(Listener listener);

    void publish(const EnvironmentState& next);
 
    // ── Test hooks ──────────────────────────────────────────────────
    static void inject_for_test(const EnvironmentState& state);

    static void reset_for_test();
 
private:
    Environment() = default;
    Environment(const Environment&) = delete;
    Environment& operator=(const Environment&) = delete;
 
    void unsubscribe(uint64_t id);
 
    mutable std::mutex mu_;
    EnvironmentState   state_;
    // Entry carries an `active` flag so `publish` can take a snapshot
    // of the subscription list under the lock, then drop the lock and
    // still skip any listener that was unsubscribed in the meantime —
    // either by another listener during the same dispatch or by a
    // different thread calling `Token::reset()`. Using shared_ptr so
    // the copy in `publish` and the live list share the same flag.
    struct Entry {
        uint64_t id;
        Listener fn;
        std::shared_ptr<std::atomic<bool>> active;
    };
    std::vector<Entry> listeners_;
    uint64_t           next_id_ = 1;
};
 
// ── Per-platform observer bootstraps ─────────────────────────────────
// Hosts call start_environment_observer() once during startup. Each
// platform adapter is idempotent — duplicate calls are a no-op so
// plugin hosts loaded multiple times don't double-register.
//
// Adapters land per platform; this header forward-declares them
// alphabetically. The convenience wrapper at the bottom dispatches to
// the right one based on the build target.
 
#if defined(__APPLE__)
#include <TargetConditionals.h>
#endif
 
#if defined(__APPLE__) && TARGET_OS_IPHONE
void start_environment_observer_ios();
#elif defined(__APPLE__)
void start_environment_observer_mac();
#endif
#if defined(__linux__) && !defined(__ANDROID__)
void start_environment_observer_linux();
#endif
#if defined(_WIN32)
void start_environment_observer_win();
#endif
 
// Use Apple's TargetConditionals.h macro rather than the CMake-defined
// PULP_IOS variable — the CMake iOS branch adds environment_ios.mm to
// pulp-platform but does not define PULP_IOS for the target, so before
// this change an iOS build would fall through to the macOS branch and
// try to link start_environment_observer_mac() (which is not in the
// iOS source set). TARGET_OS_IPHONE is always defined on Apple via
// TargetConditionals.h and is 1 only for iOS/tvOS/watchOS.
inline void start_environment_observer() {
#if defined(__APPLE__) && TARGET_OS_IPHONE
    start_environment_observer_ios();
#elif defined(__APPLE__)
    start_environment_observer_mac();
#elif defined(__linux__) && !defined(__ANDROID__)
    start_environment_observer_linux();
#elif defined(_WIN32)
    start_environment_observer_win();
#endif
    // Other platforms can add adapters later; until then
    // their hosts simply see the EnvironmentState defaults.
}
 
} // namespace pulp::platform