Update documentation

doc/changes.qbk

@@ -14,6 +14,8 @@
   `constexpr` on recent MSVC versions (VS2019 update 5 and later.)
 * Added `boost::core::byteswap` (an implementation of `std::byteswap` from
   C++23) to [link core.bit `boost/core/bit.hpp`].
+* Moved the yield primitives `sp_thread_pause`, `sp_thread_yield`, `sp_thread_sleep`
+  from SmartPtr implementation details to `boost/core/yield_primitives.hpp`.
 
 [endsect]
 

doc/core.qbk

@@ -83,3 +83,4 @@ criteria for inclusion is that the utility component be:
 [include uncaught_exceptions.qbk]
 [include use_default.qbk]
 [include verbose_terminate_handler.qbk]
+[include yield_primitives.qbk]

doc/yield_primitives.qbk

@@ -0,0 +1,79 @@
+[/
+  Copyright 2023 Peter Dimov
+  Distributed under the Boost Software License, Version 1.0.
+  https://boost.org/LICENSE_1_0.txt
+]
+
+[section:yield_primitives Yield Primitives]
+
+[simplesect Authors]
+
+* Peter Dimov
+
+[endsimplesect]
+
+[section Header <boost/core/yield_primitives.hpp>]
+
+The header `<boost/core/yield_primitives.hpp>` implements a
+collection of primitives that allow the current thread to
+yield the CPU in various ways.
+
+Very low level, specialized functionality, generally only useful for
+implementing spinlocks. Normal synchronization primitives should
+almost always be preferable in application code.
+
+[section Synopsis]
+
+``
+namespace boost
+{
+namespace core
+{
+
+void sp_thread_pause() noexcept;
+void sp_thread_yield() noexcept;
+void sp_thread_sleep() noexcept;
+
+} // namespace core
+} // namespace boost
+``
+
+[endsect]
+
+[section sp_thread_pause]
+
+`void sp_thread_pause() noexcept;`
+
+Emits a PAUSE instruction (on x86) or a YIELD instruction (on ARM).
+
+A portable equivalent of the GCC builtin function `__builtin_ia32_pause`.
+
+[endsect]
+
+[section sp_thread_yield]
+
+`void sp_thread_yield() noexcept;`
+
+Informs the scheduler that the current thread wishes to relinquish
+the rest of its timeslice.
+
+A portable equivalent of POSIX `sched_yield`.
+
+[endsect]
+
+[section sp_thread_sleep]
+
+`void sp_thread_sleep() noexcept;`
+
+Sleeps for a short period, as if by calling POSIX `nanosleep` with
+a small, implementation-dependent, interval (usually one microsecond).
+
+A more forcing yield primitive than `sp_thread_yield`, because it's
+generally not ignored even if all other waiting threads are of lower
+priority.
+
+[endsect]
+
+[endsect]
+
+[endsect]