[libcxx-commits] [libcxx] 346ef5e - [libc++][NFC] Improve documentation of the various random_device implementations

[Louis Dionne via libcxx-commits]

Author: Louis Dionne
Date: 2021-12-21T15:32:09-05:00
New Revision: 346ef5e5879e9143fe008c35c3dd6ea3c402634a

URL: https://github.com/llvm/llvm-project/commit/346ef5e5879e9143fe008c35c3dd6ea3c402634a
DIFF: https://github.com/llvm/llvm-project/commit/346ef5e5879e9143fe008c35c3dd6ea3c402634a.diff

LOG: [libc++][NFC] Improve documentation of the various random_device implementations

Also, move the setting of the macro closer to its point of use, which
also has the benefit of uncluttering `__config`.

Added: 
    

Modified: 
    libcxx/include/__config
    libcxx/include/__random/random_device.h

Removed: 
    


################################################################################
diff  --git a/libcxx/include/__config b/libcxx/include/__config
index 84ce728ac3a00..7d6cc16f7ac08 100644
--- a/libcxx/include/__config
+++ b/libcxx/include/__config
@@ -333,25 +333,6 @@
 #  define _LIBCPP_SHORT_WCHAR   1
 #endif
 
-#if defined(__OpenBSD__)
-   // Certain architectures provide arc4random(). Prefer using
-   // arc4random() over /dev/{u,}random to make it possible to obtain
-   // random data even when using sandboxing mechanisms such as chroots,
-   // Capsicum, etc.
-#  define _LIBCPP_USING_ARC4_RANDOM
-#elif defined(__Fuchsia__) || defined(__wasi__)
-#  define _LIBCPP_USING_GETENTROPY
-#elif defined(__native_client__)
-   // NaCl's sandbox (which PNaCl also runs in) doesn't allow filesystem access,
-   // including accesses to the special files under /dev. C++11's
-   // std::random_device is instead exposed through a NaCl syscall.
-#  define _LIBCPP_USING_NACL_RANDOM
-#elif defined(_LIBCPP_WIN32API)
-#  define _LIBCPP_USING_WIN32_RANDOM
-#else
-#  define _LIBCPP_USING_DEV_RANDOM
-#endif
-
 #if !defined(_LIBCPP_LITTLE_ENDIAN) && !defined(_LIBCPP_BIG_ENDIAN)
 #  include <endian.h>
 #  if __BYTE_ORDER == __LITTLE_ENDIAN

diff  --git a/libcxx/include/__random/random_device.h b/libcxx/include/__random/random_device.h
index 835f726fdbccc..82dd1a1117235 100644
--- a/libcxx/include/__random/random_device.h
+++ b/libcxx/include/__random/random_device.h
@@ -23,6 +23,50 @@ _LIBCPP_BEGIN_NAMESPACE_STD
 
 #if !defined(_LIBCPP_HAS_NO_RANDOM_DEVICE)
 
+// Libc++ supports various implementations of std::random_device.
+//
+// _LIBCPP_USING_DEV_RANDOM
+//      Read entropy from the given file, by default `/dev/urandom`.
+//      If a token is provided, it is assumed to be the path to a file
+//      to read entropy from. This is the default behavior if nothing
+//      else is specified. This implementation requires storing state
+//      inside `std::random_device`.
+//
+// _LIBCPP_USING_ARC4_RANDOM
+//      Use arc4random(). This allows obtaining random data even when
+//      using sandboxing mechanisms. On some platforms like Apple, this
+//      is the recommended source of entropy for user-space programs.
+//      When this option is used, the token passed to `std::random_device`'s
+//      constructor *must* be "/dev/urandom" -- anything else is an error.
+//
+// _LIBCPP_USING_GETENTROPY
+//      Use getentropy().
+//      When this option is used, the token passed to `std::random_device`'s
+//      constructor *must* be "/dev/urandom" -- anything else is an error.
+//
+// _LIBCPP_USING_NACL_RANDOM
+//      NaCl's sandbox (which PNaCl also runs in) doesn't allow filesystem access,
+//      including accesses to the special files under `/dev`. This implementation
+//      uses the NaCL syscall `nacl_secure_random_init()` to get entropy.
+//      When this option is used, the token passed to `std::random_device`'s
+//      constructor *must* be "/dev/urandom" -- anything else is an error.
+//
+// _LIBCPP_USING_WIN32_RANDOM
+//      Use rand_s(), for use on Windows.
+//      When this option is used, the token passed to `std::random_device`'s
+//      constructor *must* be "/dev/urandom" -- anything else is an error.
+#if defined(__OpenBSD__)
+#  define _LIBCPP_USING_ARC4_RANDOM
+#elif defined(__Fuchsia__) || defined(__wasi__)
+#  define _LIBCPP_USING_GETENTROPY
+#elif defined(__native_client__)
+#  define _LIBCPP_USING_NACL_RANDOM
+#elif defined(_LIBCPP_WIN32API)
+#  define _LIBCPP_USING_WIN32_RANDOM
+#else
+#  define _LIBCPP_USING_DEV_RANDOM
+#endif
+
 class _LIBCPP_TYPE_VIS random_device
 {
 #ifdef _LIBCPP_USING_DEV_RANDOM