Automated g4 rollback of changelist 267236680.

*** Reason for rollback ***

Roll-forward (i.e. rollback of rollback) after fixing the breakage that caused the initial rollback.  This CL has three fixes:
(1) It incorporates the fixes by varconst@ in CL 267229592, which fixed a problem where
    some of the references to std::function were not inside
    "#if defined(FIREBASE_USE_STD_FUNCTION)".
(2) It deletes an unnecessary (and wrong) friend declaration that was causing an ambiguity error; there's no need to declare the nested class intrusive_list::intrusive_list_iterator as a friend, since the containing class intrusive_list is already a friend, and the nested class has the same access as the containing class. The invalid friend declaration was implicitly declaring a non-nested class of the same name, causing later references to that name to be ambiguous.
(3) It adds a missing "const" to the declarations of some copy-constructor and assignment operators (that are only declared, not defined).

This CL is best reviewed by ticking the "Diff against rollback base revisions" box in Critique.

*** Original change description ***

Automated g4 rollback of changelist 267110370.

*** Reason for rollback ***

Fails to compile on Windows.

Can test a fix via:
blaze build --config=msvc //firebase/app/client/cpp:app_kokoro

*** Original change description ***

Add support for multiple completion handlers to Future.

This includes support for both adding and removing callbacks,
including removing callbacks added as std::function<...>.
OnCompletion() does not remove completions added with AddCompletion().

The implementation uses...

***

PiperOrigin-RevId: 267398802

Author: Googler

app/CMakeLists.txt

@@ -220,6 +220,7 @@ set(utility_common_HDRS
     src/embedded_file.h
     src/function_registry.h
     src/future_manager.h
+    src/intrusive_list.h
     src/log.h
     src/mutex.h
     src/optional.h

app/src/include/firebase/future.h

@@ -37,6 +37,7 @@ namespace FIREBASE_NAMESPACE {
 /// @cond FIREBASE_APP_INTERNAL
 namespace detail {
 class FutureApiInterface;
+class CompletionCallbackHandle;
 }  // namespace detail
 /// @endcond
 
@@ -84,6 +85,12 @@ class FutureBase {
   typedef void (*CompletionCallback)(const FutureBase& result_data,
                                      void* user_data);
 
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// Handle, representing a completion callback, that can be passed to
+  /// RemoveOnCompletion.
+  using CompletionCallbackHandle = detail::CompletionCallbackHandle;
+#endif
+
   /// Construct an untyped future.
   FutureBase();
 
@@ -139,34 +146,113 @@ class FutureBase {
   /// pending. Cast is required since GetFutureResult() returns void*.
   const void* result_void() const;
 
-  /// Register a callback that will be called at most once, when the future is
-  /// completed.
+  /// Register a single callback that will be called at most once, when the
+  /// future is completed.
+  ///
+  /// If you call any OnCompletion() method more than once on the same future,
+  /// only the most recent callback you registered with OnCompletion() will be
+  /// called.
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// However completions registered with AddCompletion() will still be
+  /// called even if there is a subsequent call to OnCompletion().
   ///
-  /// If you call any OnCompletion() method more than once, only the most recent
-  /// callback you registered will be called.
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
+#endif
   ///
   /// When your callback is called, the user_data that you supplied here will be
   /// passed back as the second parameter.
   ///
   /// @param[in] callback Function pointer to your callback.
   /// @param[in] user_data Optional user data. We will pass this back to your
   /// callback.
-  void OnCompletion(CompletionCallback callback, void* user_data) const;
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  CompletionCallbackHandle
+#else
+  void
+#endif
+  OnCompletion(CompletionCallback callback, void* user_data) const;
+
+#if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+  /// Register a single callback that will be called at most once, when the
+  /// future is completed.
+  ///
+  /// If you call any OnCompletion() method more than once on the same future,
+  /// only the most recent callback you registered with OnCompletion() will be
+  /// called.
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// However completions registered with AddCompletion() will still be
+  /// called even if there is a subsequent call to OnCompletion().
+  ///
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
+#endif
+  ///
+  /// @param[in] callback Function or lambda to call.
+  ///
+  /// @note This method is not available when using STLPort on Android, as
+  /// `std::function` is not supported on STLPort.
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  CompletionCallbackHandle
+#else
+  void
+#endif
+  OnCompletion(std::function<void(const FutureBase&)> callback) const;
+#endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// Like OnCompletion, but allows adding multiple callbacks.
+  ///
+  /// If you call AddCompletion() more than once, all of the completions that
+  /// you register will be called, when the future is completed.  However, any
+  /// callbacks which were subsequently removed by calling RemoveOnCompletion
+  /// will not be called.
+  ///
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
+  ///
+  /// @param[in] callback Function pointer to your callback.
+  /// @param[in] user_data Optional user data. We will pass this back to your
+  /// callback.
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  CompletionCallbackHandle
+  AddOnCompletion(CompletionCallback callback, void* user_data) const;
 
 #if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
-  /// Register a callback that will be called at most once, when the future is
-  /// completed.
+  /// Like OnCompletion, but allows adding multiple callbacks.
   ///
-  /// If you call any OnCompletion() method more than once, only the most recent
-  /// callback you registered will be called.
+  /// If you call AddCompletion() more than once, all of the completions that
+  /// you register will be called, when the future is completed.  However, any
+  /// callbacks which were subsequently removed by calling RemoveOnCompletion
+  /// will not be called.
+  ///
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
   ///
   /// @param[in] callback Function or lambda to call.
+  /// @return A handle that can be passed to RemoveOnCompletion.
   ///
   /// @note This method is not available when using STLPort on Android, as
   /// `std::function` is not supported on STLPort.
-  void OnCompletion(std::function<void(const FutureBase&)> callback) const;
+  CompletionCallbackHandle AddOnCompletion(
+      std::function<void(const FutureBase&)> callback) const;
+
 #endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
 
+  /// Unregisters a callback that was previously registered with
+  /// AddOnCompletion or OnCompletion.
+  ///
+  /// @param[in] completion_handle The return value of a previous call to
+  ///                              AddOnCompletion or OnCompletion.
+  void RemoveOnCompletion(CompletionCallbackHandle completion_handle) const;
+#endif  // defined(INTERNAL_EXPERIMENTAL)
+
   /// Returns true if the two Futures reference the same result.
   bool operator==(const FutureBase& rhs) const {
     return api_ == rhs.api_ && handle_ == rhs.handle_;
@@ -282,11 +368,11 @@ class Future : public FutureBase {
     return static_cast<const ResultType*>(result_void());
   }
 
-  /// Register a callback that will be called at most once, when the future is
-  /// completed.
+  /// Register a single callback that will be called at most once, when the
+  /// future is completed.
   ///
-  /// If you call any OnCompletion() method more than once, only the most recent
-  /// callback you registered will be called.
+  /// If you call any OnCompletion() method more than once on the same future,
+  /// only the most recent callback you registered will be called.
   ///
   /// When your callback is called, the user_data that you supplied here will be
   /// passed back as the second parameter.
@@ -298,17 +384,20 @@ class Future : public FutureBase {
   /// @note This is the same callback as FutureBase::OnCompletion(), so you
   /// can't expect to set both and have both run; again, only the most recently
   /// registered one will run.
-  void OnCompletion(TypedCompletionCallback callback, void* user_data) const {
-    FutureBase::OnCompletion(reinterpret_cast<CompletionCallback>(callback),
-                             user_data);
-  }
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  inline CompletionCallbackHandle
+#else
+  inline void
+#endif
+  OnCompletion(TypedCompletionCallback callback, void* user_data) const;
 
 #if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
-  /// Register a callback that will be called at most once, when the future is
-  /// completed.
+  /// Register a single callback that will be called at most once, when the
+  /// future is completed.
   ///
-  /// If you call any OnCompletion() method more than once, only the most recent
-  /// callback you registered will be called.
+  /// If you call any OnCompletion() method more than once on the same future,
+  /// only the most recent callback you registered will be called.
   ///
   /// @param[in] callback Function or lambda to call.
   ///
@@ -318,12 +407,56 @@ class Future : public FutureBase {
   /// @note This is the same callback as FutureBase::OnCompletion(), so you
   /// can't expect to set both and have both run; again, only the most recently
   /// registered one will run.
-  void OnCompletion(
-      std::function<void(const Future<ResultType>&)> callback) const {
-    FutureBase::OnCompletion(
-        *reinterpret_cast<std::function<void(const FutureBase&)>*>(&callback));
-  }
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  inline CompletionCallbackHandle
+#else
+  inline void
+#endif
+  OnCompletion(std::function<void(const Future<ResultType>&)> callback) const;
+#endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// Like OnCompletion, but allows adding multiple callbacks.
+  ///
+  /// If you call AddCompletion() more than once, all of the completions that
+  /// you register will be called, when the future is completed.  However, any
+  /// callbacks which were subsequently removed by calling RemoveOnCompletion
+  /// will not be called.
+  ///
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
+  ///
+  /// @param[in] callback Function pointer to your callback.
+  /// @param[in] user_data Optional user data. We will pass this back to your
+  /// callback.
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  inline CompletionCallbackHandle
+  AddOnCompletion(TypedCompletionCallback callback, void* user_data) const;
+
+#if defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+  /// Like OnCompletion, but allows adding multiple callbacks.
+  ///
+  /// If you call AddCompletion() more than once, all of the completions that
+  /// you register will be called, when the future is completed.  However, any
+  /// callbacks which were subsequently removed by calling RemoveOnCompletion
+  /// will not be called.
+  ///
+  /// When the future completes, first the most recent callback registered with
+  /// OnCompletion(), if any, will be called; then all callbacks registered with
+  /// AddCompletion() will be called, in the order that they were registered.
+  ///
+  /// @param[in] callback Function or lambda to call.
+  /// @return A handle that can be passed to RemoveOnCompletion.
+  ///
+  /// @note This method is not available when using STLPort on Android, as
+  /// `std::function` is not supported on STLPort.
+  inline CompletionCallbackHandle
+  AddOnCompletion(std::function<void(const Future<ResultType>&)> callback)
+      const;
 #endif  // defined(FIREBASE_USE_STD_FUNCTION) || defined(DOXYGEN)
+#endif  // defined(INTERNAL_EXPERIMENTAL)
 };
 
 // NOLINTNEXTLINE - allow namespace overridden