uint_divisor, lifted from thrift Fast64BitRemainderCalculator

Summary:
Lift `apache::thrift::frozen::detail::Fast64BitRemainderCalculator` into a new public header `folly/math/Division.h` as `folly::uint_divisor<Word>`, generalized to all unsigned integer types.

Uses Lemire's constant-divisor technique (credited in doc-comments). Key changes vs. the thrift original:
- Support all unsigned integer types, possibly falling back to integer division.
- Support zero divisors since the optimized algorithm does not perform division.
- Calculates composite division and remainder, division, or remainder.
- `constexpr` construction and invocation.
- Invocable-object usage with `operator()` in addition to `divrem`. Mathematical operator usage with `operator/` and `operator%` in addition to `div` and `rem`.
- Thrift uses Lemire’s direct fast-remainder algorithm: multiply by a precomputed reciprocal, then perform another widened multiply to recover the remainder. uint_divisor uses the same reciprocal to compute the exact quotient and derives the remainder as dividend - quotient * divisor. For 64-bit words this reduces the hot path from roughly four multiplies to three while remaining branchless. Narrow types retain Lemire’s direct remainder path where it benchmarks faster.
- Hold the original divisor in addition to the computed multiplier to support mathematical operator usage. This increases in-situ object size.
- Add `uint_divisor<Word>::calc` that does not hold the original divisor; let both `uint_divisor` and `Fast64BitRemainderCalculator` delegate to it.

Reviewed By: iahs

Differential Revision: D115907214

fbshipit-source-id: de6d55b8dac71489f4f36b382eeb9e065380cad1

Author: yfeldblum

third-party/folly/src/CMakeLists.txt

@@ -802,6 +802,10 @@ if (BUILD_TESTS OR BUILD_BENCHMARKS)
       TEST lang_to_ascii_test SOURCES ToAsciiTest.cpp
       TEST lang_type_info_test SOURCES TypeInfoTest.cpp
 
+    DIRECTORY math/test/
+      BENCHMARK math_division_bench SOURCES DivisionBench.cpp
+      TEST math_division_test SOURCES DivisionTest.cpp
+
     DIRECTORY memory/test/
       TEST memory_arena_test WINDOWS_DISABLED SOURCES ArenaTest.cpp
       TEST memory_reentrant_allocator_test WINDOWS_DISABLED

third-party/folly/src/folly/math/CMakeLists.txt

@@ -22,6 +22,16 @@ folly_add_library(
     folly_math_kahan_summation
 )
 
+folly_add_library(
+  NAME division
+  HEADERS
+    Division.h
+  EXPORTED_DEPS
+    folly_lang_assume
+    folly_portability
+    folly_traits
+)
+
 folly_add_library(
   NAME float_control
   HEADERS