Improve the documentation of Assume.h

Summary:
We have noticed some inappropriate uses of `assume_unreachable()`, and we believe that the documentation does not convey strongly enough that it is not an assertion.

This diff moves the implementation to a separate header (as the assertions in there might be misleading) and fleshes out more the intended use cases.

Reviewed By: yfeldblum, mkatsevVR, luciang

Differential Revision: D20182339

fbshipit-source-id: 8a3be1ada06dead7ea936971c42c4f30389fc23a

folly/lang/Assume-inl.h

+/*
+ * Copyright (c) Facebook, Inc. and its 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.
+ */
+
+#pragma once
+
+#include <cstdlib>
+
+#include <folly/Portability.h>
+
+namespace folly {
+
+namespace detail {
+
+extern void assume_check(bool cond);
+
+} // namespace detail
+
+FOLLY_ALWAYS_INLINE void assume(bool cond) {
+  if (kIsDebug) {
+    detail::assume_check(cond);
+  } else {
+#if defined(__clang__) // Must go first because Clang also defines __GNUC__.
+    __builtin_assume(cond);
+#elif defined(__GNUC__)
+    if (!cond) {
+      __builtin_unreachable();
+    }
+#elif defined(_MSC_VER)
+    __assume(cond);
+#else
+    // Do nothing.
+#endif
+  }
+}
+
+[[noreturn]] FOLLY_ALWAYS_INLINE void assume_unreachable() {
+  assume(false);
+  // Do a bit more to get the compiler to understand
+  // that this function really will never return.
+#if defined(__GNUC__)
+  __builtin_unreachable();
+#elif defined(_MSC_VER)
+  __assume(0);
+#else
+  // Well, it's better than nothing.
+  std::abort();
+#endif
+}
+
+} // namespace folly

folly/lang/Assume.h

@@ -16,58 +16,54 @@
 
 #pragma once
 
-#include <cstdlib>
-
 #include <folly/Portability.h>
 
 namespace folly {
 
-namespace detail {
-
-extern void assume_check(bool cond);
-
-} // namespace detail
-
 /**
- * Inform the compiler that the argument can be assumed true. It is
- * undefined behavior if the argument is not actually true, so use
- * with care.
+ * assume*() functions can be used to fine-tune optimizations or suppress
+ * warnings when certain conditions are provably true, but the compiler is not
+ * able to prove them.
  *
- * Implemented as a function instead of a macro because
- * __builtin_assume does not evaluate its argument at runtime, so it
- * cannot be used with expressions that have side-effects.
+ * This is different from assertions: an assertion will place an explicit check
+ * that the condition is true, and abort the program if the condition is not
+ * verified. Calling assume*() with a condition that is not true at runtime
+ * is undefined behavior: for example, it may or may not result in a crash,
+ * silently corrupt memory, or jump to a random code path.
+ *
+ * These functions should only be used on conditions that are provable internal
+ * logic invariants; they cannot be used safely if the condition depends on
+ * external inputs or data. To detect unexpected conditions that *can* happen,
+ * an assertion or exception should be used.
  */
 
-FOLLY_ALWAYS_INLINE void assume(bool cond) {
-  if (kIsDebug) {
-    detail::assume_check(cond);
-  } else {
-#if defined(__clang__) // Must go first because Clang also defines __GNUC__.
-    __builtin_assume(cond);
-#elif defined(__GNUC__)
-    if (!cond) {
-      __builtin_unreachable();
-    }
-#elif defined(_MSC_VER)
-    __assume(cond);
-#else
-    // Do nothing.
-#endif
-  }
-}
+/**
+ * assume(cond) informs the compiler that cond can be assumed true. If cond is
+ * not true at runtime the behavior is undefined.
+ *
+ * The typical use case is to allow the compiler exploit data structure
+ * invariants that can trigger better optimizations, for example to eliminate
+ * unnecessary bounds checks in a called function. It is recommended to check
+ * the generated code or run microbenchmarks to assess whether it is actually
+ * effective.
+ *
+ * The semantics are similar to clang's __builtin_assume(), but intentionally
+ * implemented as a function to force the evaluation of its argument, contrary
+ * to the builtin, which cannot used with expressions that have side-effects.
+ */
+FOLLY_ALWAYS_INLINE void assume(bool cond);
 
-[[noreturn]] FOLLY_ALWAYS_INLINE void assume_unreachable() {
-  assume(false);
-  // Do a bit more to get the compiler to understand
-  // that this function really will never return.
-#if defined(__GNUC__)
-  __builtin_unreachable();
-#elif defined(_MSC_VER)
-  __assume(0);
-#else
-  // Well, it's better than nothing.
-  std::abort();
-#endif
-}
+/**
+ * assume_unreachable() informs the compiler that the statement is not reachable
+ * at runtime. It is undefined behavior if the statement is actually reached.
+ *
+ * Common use cases are to suppress a warning when the compiler cannot prove
+ * that the end of a non-void function is not reachable, or to optimize the
+ * evaluation of switch/case statements when all the possible values are
+ * provably enumerated.
+ */
+[[noreturn]] FOLLY_ALWAYS_INLINE void assume_unreachable();
 
 } // namespace folly
+
+#include <folly/lang/Assume-inl.h>