Add blocking methods Wait() and Await() to FutureBase and Future

(respectively).  Wait() just blocks until the future is completed,
or a timeout expires.  Await() blocks until the future is completed,
or a timeout expires, and then returns a pointer to the future's result,
or nullptr if the timeout expired.

PiperOrigin-RevId: 267625598

Author: Googler

app/CMakeLists.txt

@@ -134,6 +134,7 @@ set(common_SRCS
     src/callback.cc
     src/cleanup_notifier.cc
     src/function_registry.cc
+    src/future.cc
     src/future_manager.cc
     src/path.cc
     src/reference_counted_future_impl.cc

app/src/future.cc

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "app/src/include/firebase/future.h"
+
+#include "app/src/semaphore.h"
+
+#if !defined(FIREBASE_NAMESPACE)
+#define FIREBASE_NAMESPACE firebase
+#endif
+
+namespace FIREBASE_NAMESPACE {
+
+namespace {
+
+// Callback function installed by FutureBase::Wait().
+// This will be called when the future is complete.
+void WaitCallback(const FutureBase &, void *user_data) {
+  Semaphore *semaphore = static_cast<Semaphore *>(user_data);
+  // Wake up the thread that called Wait().
+  semaphore->Post();
+}
+
+}  // anonymous namespace
+
+const int FutureBase::kWaitTimeoutInfinite = -1;
+
+bool FutureBase::Wait(int timeout_milliseconds) const {
+  Semaphore semaphore(0);
+  auto callback_handle = AddOnCompletion(WaitCallback, &semaphore);
+  if (timeout_milliseconds == kWaitTimeoutInfinite) {
+    semaphore.Wait();
+    return true;
+  } else {
+    bool completed = semaphore.TimedWait(timeout_milliseconds);
+    if (!completed) {
+      RemoveOnCompletion(callback_handle);
+    }
+    return completed;
+  }
+}
+
+// NOLINTNEXTLINE - allow namespace overridden
+}  // namespace FIREBASE_NAMESPACE

app/src/include/firebase/future.h

@@ -146,6 +146,27 @@ class FutureBase {
   /// pending. Cast is required since GetFutureResult() returns void*.
   const void* result_void() const;
 
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// Special timeout value indicating an infinite timeout.
+  ///
+  /// Passing this value to FutureBase::Wait() or Future<T>::Await() will cause
+  /// those methods to wait until the future is complete.
+  ///
+  /// @Warning It is inadvisable to use this from code that could be called
+  /// from an event loop.
+  static const int kWaitTimeoutInfinite;
+
+  /// Block (i.e. suspend the current thread) until either the future is
+  /// completed or the specified timeout period (in milliseconds) has elapsed.
+  /// If `timeout_milliseconds` is `kWaitTimeoutInfinite`, then the timeout
+  /// period is treated as being infinite, i.e. this will block until the
+  /// future is completed.
+  ///
+  /// @return True if the future completed, or
+  ///         false if the timeout period elapsed before the future completed.
+  bool Wait(int timeout_milliseconds) const;
+#endif  // defined(INTERNAL_EXPERIMENTAL)
+
   /// Register a single callback that will be called at most once, when the
   /// future is completed.
   ///
@@ -368,6 +389,22 @@ class Future : public FutureBase {
     return static_cast<const ResultType*>(result_void());
   }
 
+#if defined(INTERNAL_EXPERIMENTAL)
+  /// Waits (blocks) until either the future is completed, or the specified
+  /// timeout period (in milliseconds) has elapsed, then returns the result of
+  /// the asynchronous call.
+  ///
+  /// This is a convenience method that calls Wait() and then returns result().
+  ///
+  /// If `timeout_milliseconds` is `kWaitTimeoutInfinite`, then the timeout
+  /// period is treated as being infinite, i.e. this will block until the
+  /// future is completed.
+  const ResultType* Await(int timeout_milliseconds) const {
+    Wait(timeout_milliseconds);
+    return result();
+  }
+#endif  // defined(INTERNAL_EXPERIMENTAL)
+
   /// Register a single callback that will be called at most once, when the
   /// future is completed.
   ///

app/src/thread_pthread.cc

@@ -146,4 +146,5 @@ void Thread::Detach() {
 
 // NOLINTNEXTLINE - allow namespace overridden
 }  // namespace FIREBASE_NAMESPACE
-#endif
+
+#endif  // defined(_STLPORT_VERSION)