feat: add StartAsync (#110)

This PR adds `StartAsync`, which allows users to wait on initialization
using a future. C bindings have been updated to allow for waiting.

Author: cwaldren-ld

apps/hello-c/main.c

@@ -45,6 +45,16 @@ int main() {
     LDContext context = LDContextBuilder_Build(context_builder);
 
     LDClientSDK client = LDClientSDK_New(config, context);
+
+    bool initialized_successfully;
+    if (LDClientSDK_Start(client, 5000, &initialized_successfully)) {
+        printf("SDK initialized successfully: %s\n",
+               (initialized_successfully ? "true" : "false"));
+    } else {
+        printf("SDK couldn't initialize in time; quitting\n");
+        return 1;
+    }
+
     //
     //    std::cout << "Initial Status: " << client.DataSourceStatus().Status()
     //              << std::endl;

apps/hello-cpp/main.cpp

@@ -118,7 +118,14 @@ int main() {
         std::cout << "Got flag change: " << *event << std::endl;
     });
 
-    client.WaitForReadySync(std::chrono::seconds(30));
+    auto started = client.StartAsync();
+    auto status = started.wait_for(std::chrono::seconds(5));
+    if (status == std::future_status::ready) {
+        std::cout << "SDK initialized successfully: "
+                  << (started.get() ? "true" : "false") << std::endl;
+    } else {
+        std::cout << "SDK didn't initialize in time; quitting" << std::endl;
+    }
 
     auto value = client.BoolVariationDetail("my-boolean-flag", false);
     std::cout << "Value was: " << *value << std::endl;

apps/sdk-contract-tests/src/client_entity.cpp

@@ -35,7 +35,15 @@ tl::expected<nlohmann::json, std::string> ClientEntity::Identify(
         return tl::make_unexpected(maybe_ctx->errors());
     }
 
-    client_->IdentifyAsync(*maybe_ctx).wait();
+    // The typical way to identify in contract tests would be .wait(), to ensure
+    // identify completes fully before proceeding. Some of the contract tests
+    // send invalid data to the data source though, so identify will never
+    // complete because the data source can't start. So, limit the amount of
+    // time such that: 1) For most tests, this is *basically* synchronous 2) For
+    // the problematic tests, this eventually does unblock and let the test
+    // proceed.
+    // TODO: SC-204250
+    client_->IdentifyAsync(*maybe_ctx).wait_for(std::chrono::seconds(5));
     return nlohmann::json{};
 }
 

apps/sdk-contract-tests/src/entity_manager.cpp

@@ -143,7 +143,9 @@ std::optional<std::string> EntityManager::create(ConfigParams const& in) {
     if (in.startWaitTimeMs) {
         waitForClient = std::chrono::milliseconds(*in.startWaitTimeMs);
     }
-    client->WaitForReadySync(waitForClient);
+
+    auto init = client->StartAsync();
+    init.wait_for(waitForClient);
 
     entities_.try_emplace(id, std::move(client));
 

apps/sdk-contract-tests/test-suppressions.txt

@@ -1,6 +1,3 @@
-events/summary events/basic counter behavior
-events/summary events/reset after each flush
-
 # The Client doesn't need to know how to deserialize users.
 context type/convert/old user to context/{"key": ""}
 context type/convert/old user to context/{"key": "a"}

libs/client-sdk/include/launchdarkly/client_side/bindings/c/sdk.h

@@ -31,19 +31,72 @@ typedef struct _LDClientSDK* LDClientSDK;
 LD_EXPORT(LDClientSDK)
 LDClientSDK_New(LDClientConfig config, LDContext context);
 
+/**
+ * Starts the SDK, initiating a connection to LaunchDarkly if not offline.
+ *
+ * Only one Start call can be in progress at once; calling it
+ * concurrently invokes undefined behavior.
+ *
+ * The method may be blocking or asynchronous depending on the arguments.
+ *
+ * To block, pass a positive milliseconds value and an optional pointer to a
+ boolean. The return
+ * value will be true if the SDK started within the specified timeframe, or
+ false if the
+ * operation couldn't complete in time. The value of out_succeeded will be true
+ * if the SDK successfully initialized.
+ *
+ * Example:
+ * @code
+ * bool initialized_successfully;
+ * if (LDClientSDK_Start(client, 5000, &initialized_successfully)) {
+ *     // The client was able to initialize in less than 5 seconds.
+ *     if (initialized_successfully) {
+ *         // Initialization succeeded.
+ *     else {
+ *         // Initialization failed.
+ *     }
+ * } else {
+ *    // The client is still initializing.
+ * }
+ * @endcode
+ *
+ * To start asynchronously, pass `LD_NONBLOCKING`. In this case, the return
+ value
+ * will be false and you may pass NULL to out_succeeded.
+ *
+ * @code
+ * // Returns immediately.
+ * LDClientSDK_Start(client, LD_NONBLOCKING, NULL);
+ * @endcode
+ *
+ * @param sdk SDK. Must not be NULL.
+ * @param milliseconds Milliseconds to wait for initialization or
+ `LD_NONBLOCKING` to return immediately.
+ * @param out_succeeded Pointer to bool representing successful initialization.
+ Only
+ * modified if a positive milliseconds value is passed; may be NULL.
+ * @return True if the client started within the specified timeframe.
+ */
+LD_EXPORT(bool)
+LDClientSDK_Start(LDClientSDK sdk,
+                  unsigned int milliseconds,
+                  bool* out_succeeded);
+
 /**
  * Returns a boolean value indicating LaunchDarkly connection and flag state
  * within the client.
  *
- * When you first start the client, once WaitForReadySync has returned or
- * WaitForReadyAsync has completed, Initialized should return true if
- * and only if either 1. it connected to LaunchDarkly and successfully
- * retrieved flags, or 2. it started in offline mode so there's no need to
- * connect to LaunchDarkly. If the client timed out trying to connect to LD,
- * then Initialized returns false (even if we do have cached flags).
- * If the client connected and got a 401 error, Initialized is
- * will return false. This serves the purpose of letting the app know that
- * there was a problem of some kind.
+ * When you first start the client, once Start has completed, Initialized
+ * should return true if and only if either 1. it connected to LaunchDarkly and
+ * successfully retrieved flags, or 2. it started in offline mode so there's no
+ * need to connect to LaunchDarkly.
+ *
+ * If the client timed out trying to connect to
+ * LD, then Initialized returns false (even if we do have cached flags). If the
+ * client connected and got a 401 error, Initialized is will return false. This
+ * serves the purpose of letting the app know that there was a problem of some
+ * kind.
  *
  * @param sdk SDK. Must not be NULL.
  * @return True if initialized.
@@ -89,10 +142,10 @@ LDClientSDK_TrackData(LDClientSDK sdk, char const* event_name, LDValue data);
 /**
  * Requests delivery of all pending analytic events (if any).
  *
- * You MUST pass LD_NONBLOCKING as the second parameter.
+ * You MUST pass `LD_NONBLOCKING` as the second parameter.
  *
  * @param sdk SDK. Must not be NULL.
- * @param milliseconds Must pass LD_NONBLOCKING.
+ * @param milliseconds Must pass `LD_NONBLOCKING`.
  */
 LD_EXPORT(void)
 LDClientSDK_Flush(LDClientSDK sdk, unsigned int reserved);
@@ -105,19 +158,54 @@ LDClientSDK_Flush(LDClientSDK sdk, unsigned int reserved);
  * Only one Identify call can be in progress at once; calling it
  * concurrently invokes undefined behavior.
  *
- * To block until the identify operation is complete or a timeout is reached,
- * pass a positive milliseconds parameter. Otherwise to return immediately,
- * pass LD_NONBLOCKING.
+ * The method may be blocking or asynchronous depending on the arguments.
+ *
+ * To block, pass a positive milliseconds value and an optional pointer to a
+ boolean. The return
+ * value will be true if the SDK was able to attempt the operation within
+ the specified timeframe, or false if the
+ * operation couldn't complete in time. The value of out_succeeded will be true
+ * if the SDK successfully changed evaluation contexts.
+ *
+ * Example:
+ * @code
+ * bool identified_successfully;
+ * if (LDClientSDK_Identify(client, 5000, &identified_successfully)) {
+ *     // The client was able to re-initialize in less than 5 seconds.
+ *     if (identified_successfully) {
+ *         // Evaluations will use data for the new context.
+ *     else {
+ *         // Evaluations will continue using existing data.
+ *     }
+ * } else {
+ *    // The client is still identifying.
+ * }
+ * @endcode
+ *
+ * To start asynchronously, pass `LD_NONBLOCKING`. In this case, the return
+value
+ * will be false and you may pass NULL to out_succeeded.
+ *
+ * @code
+ * // Returns immediately.
+ * LDClientSDK_Identify(client, LD_NONBLOCKING, NULL);
+ * @endcode
+ *
  *
  * @param sdk SDK. Must not be NULL.
  * @param context The new evaluation context.
- * @param milliseconds How long to wait for the identify to complete, or
- * LD_NONBLOCKING to return immediately.
+ * @param milliseconds Milliseconds to wait for identify to complete, or
+ * `LD_NONBLOCKING` to return immediately.
+ * @param out_succeeded Pointer to bool representing successful identification.
+Only
+* modified if a positive milliseconds value is passed; may be NULL.
+ * @return True if the client started within the specified timeframe.
  */
-LD_EXPORT(void)
+LD_EXPORT(bool)
 LDClientSDK_Identify(LDClientSDK sdk,
                      LDContext context,
-                     unsigned int milliseconds);
+                     unsigned int milliseconds,
+                     bool* out_succeeded);
 
 /**
  * Returns the boolean value of a feature flag for a given flag key.

libs/client-sdk/include/launchdarkly/client_side/client.hpp

@@ -21,19 +21,28 @@ namespace launchdarkly::client_side {
  */
 class IClient {
    public:
+    /** Connects the client to LaunchDarkly's flag delivery endpoints.
+     *
+     * If StartAsync isn't called, the client is able to post events but is
+     * unable to obtain flag data.
+     *
+     * The returned future will resolve to true or false based on the logic
+     * outlined on @ref Initialized.
+     */
+    virtual std::future<bool> StartAsync() = 0;
+
     /**
      * Returns a boolean value indicating LaunchDarkly connection and flag state
      * within the client.
      *
-     * When you first start the client, once WaitForReadySync has returned or
-     * WaitForReadyAsync has completed, Initialized should return true if
-     * and only if either 1. it connected to LaunchDarkly and successfully
-     * retrieved flags, or 2. it started in offline mode so there's no need to
-     * connect to LaunchDarkly. If the client timed out trying to connect to LD,
-     * then Initialized returns false (even if we do have cached flags).
-     * If the client connected and got a 401 error, Initialized is
-     * will return false. This serves the purpose of letting the app know that
-     * there was a problem of some kind.
+     * When you first start the client, once StartAsync has completed,
+     * Initialized should return true if and only if either 1. it connected to
+     * LaunchDarkly and successfully retrieved flags, or 2. it started in
+     * offline mode so there's no need to connect to LaunchDarkly. If the client
+     * timed out trying to connect to LD, then Initialized returns false (even
+     * if we do have cached flags). If the client connected and got a 401 error,
+     * Initialized is will return false. This serves the purpose of letting the
+     * app know that there was a problem of some kind.
      *
      * @return True if the client is initialized.
      */
@@ -101,10 +110,13 @@ class IClient {
      * To block until the identify operation is complete, call wait() on
      * the returned future.
      *
+     * The returned future will resolve to true or false based on the logic
+     * outlined on @ref Initialized.
+     *
      * @param context The new evaluation context.
      */
 
-    virtual std::future<void> IdentifyAsync(Context context) = 0;
+    virtual std::future<bool> IdentifyAsync(Context context) = 0;
 
     /**
      * Returns the boolean value of a feature flag for a given flag key.
@@ -230,14 +242,6 @@ class IClient {
      */
     virtual flag_manager::IFlagNotifier& FlagNotifier() = 0;
 
-    /**
-     * Wait for the client to be ready. A client will be ready when it either
-     * successfully initializes, or encounters a permanent error.
-     *
-     * @param timeout Time to wait.
-     */
-    virtual void WaitForReadySync(std::chrono::milliseconds timeout) = 0;
-
     virtual ~IClient() = default;
     IClient(IClient const& item) = delete;
     IClient(IClient&& item) = delete;
@@ -260,6 +264,8 @@ class Client : public IClient {
     Client& operator=(Client) = delete;
     Client& operator=(Client&& other) = delete;
 
+    std::future<bool> StartAsync() override;
+
     [[nodiscard]] bool Initialized() const override;
 
     using FlagKey = std::string;
@@ -275,7 +281,7 @@ class Client : public IClient {
 
     void FlushAsync() override;
 
-    std::future<void> IdentifyAsync(Context context) override;
+    std::future<bool> IdentifyAsync(Context context) override;
 
     bool BoolVariation(FlagKey const& key, bool default_value) override;
 
@@ -309,8 +315,6 @@ class Client : public IClient {
 
     flag_manager::IFlagNotifier& FlagNotifier() override;
 
-    void WaitForReadySync(std::chrono::milliseconds timeout) override;
-
    private:
     std::unique_ptr<IClient> client;
 };

libs/client-sdk/include/launchdarkly/client_side/data_source_status.hpp

@@ -66,7 +66,7 @@ class DataSourceStatus {
          * SDK key will never become valid), or because the SDK client was
          * explicitly shut down.
          */
-        kShutdown
+        kShutdown,
 
         // BackgroundDisabled,
         // TODO: A plugin of sorts would likely be required for some
@@ -208,7 +208,7 @@ class IDataSourceStatusProvider {
      * The current status of the data source. Suitable for broadcast to
      * data source status listeners.
      */
-    virtual DataSourceStatus Status() = 0;
+    virtual DataSourceStatus Status() const = 0;
 
     /**
      * Listen to changes to the data source status.
@@ -219,6 +219,17 @@ class IDataSourceStatusProvider {
     virtual std::unique_ptr<IConnection> OnDataSourceStatusChange(
         std::function<void(data_sources::DataSourceStatus status)> handler) = 0;
 
+    /**
+     * Listen to changes to the data source status, with ability for listener
+     * to unregister itself.
+     *
+     * @param handler Function which will be called with the new status. Return
+     * true to unregister.
+     * @return A IConnection which can be used to stop listening to the status.
+     */
+    virtual std::unique_ptr<IConnection> OnDataSourceStatusChangeEx(
+        std::function<bool(data_sources::DataSourceStatus status)> handler) = 0;
+
     virtual ~IDataSourceStatusProvider() = default;
     IDataSourceStatusProvider(IDataSourceStatusProvider const& item) = delete;
     IDataSourceStatusProvider(IDataSourceStatusProvider&& item) = delete;