folly/folly/Optional.h

/*
 * Copyright (c) Meta Platforms, Inc. and affiliates.
 *
 * 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.
 */

//
// Docs: https://fburl.com/fbcref_optional
//

#pragma once

/*
 * Optional - For conditional initialization of values, like boost::optional,
 * but with support for move semantics and emplacement.  Reference type support
 * has not been included due to limited use cases and potential confusion with
 * semantics of assignment: Assigning to an optional reference could quite
 * reasonably copy its value or redirect the reference.
 *
 * Optional can be useful when a variable might or might not be needed:
 *
 *  Optional<Logger> maybeLogger = ...;
 *  if (maybeLogger) {
 *    maybeLogger->log("hello");
 *  }
 *
 * Optional enables a 'null' value for types which do not otherwise have
 * nullability, especially useful for parameter passing:
 *
 * void testIterator(const unique_ptr<Iterator>& it,
 *                   initializer_list<int> idsExpected,
 *                   Optional<initializer_list<int>> ranksExpected = none) {
 *   for (int i = 0; it->next(); ++i) {
 *     EXPECT_EQ(it->doc().id(), idsExpected[i]);
 *     if (ranksExpected) {
 *       EXPECT_EQ(it->doc().rank(), (*ranksExpected)[i]);
 *     }
 *   }
 * }
 *
 * Optional models OptionalPointee, so calling 'get_pointer(opt)' will return a
 * pointer to nullptr if the 'opt' is empty, and a pointer to the value if it is
 * not:
 *
 *  Optional<int> maybeInt = ...;
 *  if (int* v = get_pointer(maybeInt)) {
 *    cout << *v << endl;
 *  }
 */

#include <cassert>
#include <cstddef>
#include <functional>
#include <new>
#include <optional>
#include <stdexcept>
#include <type_traits>
#include <utility>

#include <folly/Portability.h>
#include <folly/Traits.h>
#include <folly/Utility.h>
#include <folly/lang/Exception.h>

namespace folly {

template <class Value>
class Optional;

namespace detail {
struct OptionalEmptyTag { … };
template <class Value>
struct OptionalPromise;
template <class Value>
struct OptionalPromiseReturn;
} // namespace detail

struct None { … };
constexpr None none{ … };

class FOLLY_EXPORT OptionalEmptyException : public std::runtime_error { … };

/**
 * Optional is superseded by std::optional. Now that the C++ has a standardized
 * implementation, Optional exists primarily for backward compatibility.
 */
template <class Value>
class Optional { … };

template <class T>
const T* get_pointer(const Optional<T>& opt) { … }

template <class T>
T* get_pointer(Optional<T>& opt) { … }

template <class T>
void swap(Optional<T>& a, Optional<T>& b) noexcept(noexcept(a.swap(b))) { … }

template <class T>
constexpr Optional<std::decay_t<T>> make_optional(T&& v) { … }

template <class T, class... Args>
constexpr folly::Optional<T> make_optional(Args&&... args) { … }

template <class T, class U, class... Args>
constexpr folly::Optional<T> make_optional(
    std::initializer_list<U> il, Args&&... args) { … }

///////////////////////////////////////////////////////////////////////////////
// Comparisons.

template <class U, class V>
constexpr bool operator==(const Optional<U>& a, const V& b) { … }

template <class U, class V>
constexpr bool operator!=(const Optional<U>& a, const V& b) { … }

template <class U, class V>
constexpr bool operator==(const U& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator!=(const U& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator==(const Optional<U>& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator!=(const Optional<U>& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator<(const Optional<U>& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator>(const Optional<U>& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator<=(const Optional<U>& a, const Optional<V>& b) { … }

template <class U, class V>
constexpr bool operator>=(const Optional<U>& a, const Optional<V>& b) { … }

// Suppress comparability of Optional<T> with T, despite implicit conversion.
template <class V>
bool operator<(const Optional<V>&, const V& other) = delete;
template <class V>
bool operator<=(const Optional<V>&, const V& other) = delete;
template <class V>
bool operator>=(const Optional<V>&, const V& other) = delete;
template <class V>
bool operator>(const Optional<V>&, const V& other) = delete;
template <class V>
bool operator<(const V& other, const Optional<V>&) = delete;
template <class V>
bool operator<=(const V& other, const Optional<V>&) = delete;
template <class V>
bool operator>=(const V& other, const Optional<V>&) = delete;
template <class V>
bool operator>(const V& other, const Optional<V>&) = delete;

// Comparisons with none
template <class V>
constexpr bool operator==(const Optional<V>& a, None) noexcept { … }
template <class V>
constexpr bool operator==(None, const Optional<V>& a) noexcept { … }
template <class V>
constexpr bool operator<(const Optional<V>&, None) noexcept { … }
template <class V>
constexpr bool operator<(None, const Optional<V>& a) noexcept { … }
template <class V>
constexpr bool operator>(const Optional<V>& a, None) noexcept { … }
template <class V>
constexpr bool operator>(None, const Optional<V>&) noexcept { … }
template <class V>
constexpr bool operator<=(None, const Optional<V>&) noexcept { … }
template <class V>
constexpr bool operator<=(const Optional<V>& a, None) noexcept { … }
template <class V>
constexpr bool operator>=(const Optional<V>&, None) noexcept { … }
template <class V>
constexpr bool operator>=(None, const Optional<V>& a) noexcept { … }

///////////////////////////////////////////////////////////////////////////////

} // namespace folly

// Allow usage of Optional<T> in std::unordered_map and std::unordered_set
FOLLY_NAMESPACE_STD_BEGIN
hash<folly::enable_std_hash_helper<folly::Optional<T>, remove_const_t<T>>>;
FOLLY_NAMESPACE_STD_END

// Enable the use of folly::Optional with `co_await`
// Inspired by https://github.com/toby-allsopp/coroutine_monad
#if FOLLY_HAS_COROUTINES
#include <folly/experimental/coro/Coroutine.h>

namespace folly {
namespace detail {
template <typename Value>
struct OptionalPromise;

template <typename Value>
struct OptionalPromiseReturn {
  Optional<Value> storage_;
  Optional<Value>*& pointer_;

  /* implicit */ OptionalPromiseReturn(OptionalPromise<Value>& p) noexcept
      : pointer_{p.value_} {
    pointer_ = &storage_;
  }
  OptionalPromiseReturn(OptionalPromiseReturn const&) = delete;
  // letting dtor be trivial makes the coroutine crash
  // TODO: fix clang/llvm codegen
  ~OptionalPromiseReturn() {}
  /* implicit */ operator Optional<Value>() {
    // handle both deferred and eager return-object conversion behaviors
    // see docs for detect_promise_return_object_eager_conversion
    if (folly::coro::detect_promise_return_object_eager_conversion()) {
      assert(!storage_.has_value());
      return Optional{OptionalEmptyTag{}, pointer_}; // eager
    } else {
      return std::move(storage_); // deferred
    }
  }
};

template <typename Value>
struct OptionalPromise {
  Optional<Value>* value_ = nullptr;
  OptionalPromise() = default;
  OptionalPromise(OptionalPromise const&) = delete;
  OptionalPromiseReturn<Value> get_return_object() noexcept { return *this; }
  coro::suspend_never initial_suspend() const noexcept { return {}; }
  coro::suspend_never final_suspend() const noexcept { return {}; }
  template <typename U = Value>
  void return_value(U&& u) {
    *value_ = static_cast<U&&>(u);
  }
  void unhandled_exception() {
    // Technically, throwing from unhandled_exception is underspecified:
    // https://github.com/GorNishanov/CoroutineWording/issues/17
    rethrow_current_exception();
  }
};

template <typename Value>
struct OptionalAwaitable {
  Optional<Value> o_;
  bool await_ready() const noexcept { return o_.hasValue(); }
  Value await_resume() { return std::move(o_.value()); }

  // Explicitly only allow suspension into an OptionalPromise
  template <typename U>
  void await_suspend(coro::coroutine_handle<OptionalPromise<U>> h) const {
    // Abort the rest of the coroutine. resume() is not going to be called
    h.destroy();
  }
};
} // namespace detail

template <typename Value>
detail::OptionalAwaitable<Value>
/* implicit */ operator co_await(Optional<Value> o) {
  return {std::move(o)};
}
} // namespace folly

#endif // FOLLY_HAS_COROUTINES