experimental/status-code/status_code_domain.hpp

0001 /* Proposed SG14 status_code
0002 (C) 2018-2024 Niall Douglas <http://www.nedproductions.biz/> (5 commits)
0003 File Created: Feb 2018
0004
0005
0006 Boost Software License - Version 1.0 - August 17th, 2003
0007
0008 Permission is hereby granted, free of charge, to any person or organization
0009 obtaining a copy of the software and accompanying documentation covered by
0010 this license (the "Software") to use, reproduce, display, distribute,
0011 execute, and transmit the Software, and to prepare derivative works of the
0012 Software, and to permit third-parties to whom the Software is furnished to
0013 do so, all subject to the following:
0014
0015 The copyright notices in the Software and this entire statement, including
0016 the above license grant, this restriction and the following disclaimer,
0017 must be included in all copies of the Software, in whole or in part, and
0018 all derivative works of the Software, unless such copies or derivative
0019 works are solely in the form of machine-executable object code generated by
0020 a source language processor.
0021
0022 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
0023 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
0024 FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
0025 SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
0026 FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
0027 ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
0028 DEALINGS IN THE SOFTWARE.
0029 */
0030
0031 #ifndef BOOST_OUTCOME_SYSTEM_ERROR2_STATUS_CODE_DOMAIN_HPP
0032 #define BOOST_OUTCOME_SYSTEM_ERROR2_STATUS_CODE_DOMAIN_HPP
0033
0034 #include "config.hpp"
0035
0036 #include <cstring>  // for strchr
0037
0038 BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_BEGIN
0039
0040 /*! The main workhorse of the system_error2 library, can be typed (`status_code<DomainType>`), erased-immutable (`status_code<void>`) or erased-mutable
0041 (`status_code<erased<T>>`).
0042
0043 Be careful of placing these into containers! Equality and inequality operators are
0044 *semantic* not exact. Therefore two distinct items will test true! To help prevent
0045 surprise on this, `operator<` and `std::hash<>` are NOT implemented in order to
0046 trap potential incorrectness. Define your own custom comparison functions for your
0047 container which perform exact comparisons.
0048 */
0049 template <class DomainType> class status_code;
0050 class _generic_code_domain;
0051 //! The generic code is a status code with the generic code domain, which is that of `errc` (POSIX).
0052 using generic_code = status_code<_generic_code_domain>;
0053
0054 namespace detail
0055 {
0056   template <class StatusCode, class Allocator> class indirecting_domain;
0057   /* We are severely limited by needing to retain C++ 11 compatibility when doing
0058   constexpr string parsing. MSVC lets you throw exceptions within a constexpr
0059   evaluation context when exceptions are globally disabled, but won't let you
0060   divide by zero, even if never evaluated, ever in constexpr. GCC and clang won't
0061   let you throw exceptions, ever, if exceptions are globally disabled. So let's
0062   use the trick of divide by zero in constexpr on GCC and clang if and only if
0063   exceptions are globally disabled.
0064   */
0065 #ifdef __GNUC__
0066 #pragma GCC diagnostic push
0067 #pragma GCC diagnostic ignored "-Wdiv-by-zero"
0068 #endif
0069 #if defined(__cpp_exceptions) || (defined(_MSC_VER) && !defined(__clang__))
0070 #define BOOST_OUTCOME_SYSTEM_ERROR2_FAIL_CONSTEXPR(msg) throw msg
0071 #else
0072 #define BOOST_OUTCOME_SYSTEM_ERROR2_FAIL_CONSTEXPR(msg) ((void) msg, 1 / 0)
0073 #endif
0074   constexpr inline unsigned long long parse_hex_byte(char c)
0075   {
0076     return ('0' <= c && c <= '9') ? (c - '0') :
0077            ('a' <= c && c <= 'f') ? (10 + c - 'a') :
0078            ('A' <= c && c <= 'F') ? (10 + c - 'A') :
0079                                     BOOST_OUTCOME_SYSTEM_ERROR2_FAIL_CONSTEXPR("Invalid character in UUID");
0080   }
0081   constexpr inline unsigned long long parse_uuid2(const char *s)
0082   {
0083     return ((parse_hex_byte(s[0]) << 0) | (parse_hex_byte(s[1]) << 4) | (parse_hex_byte(s[2]) << 8) | (parse_hex_byte(s[3]) << 12) |
0084             (parse_hex_byte(s[4]) << 16) | (parse_hex_byte(s[5]) << 20) | (parse_hex_byte(s[6]) << 24) | (parse_hex_byte(s[7]) << 28) |
0085             (parse_hex_byte(s[9]) << 32) | (parse_hex_byte(s[10]) << 36) | (parse_hex_byte(s[11]) << 40) | (parse_hex_byte(s[12]) << 44) |
0086             (parse_hex_byte(s[14]) << 48) | (parse_hex_byte(s[15]) << 52) | (parse_hex_byte(s[16]) << 56) | (parse_hex_byte(s[17]) << 60))  //
0087            ^                                                                                                                                //
0088            ((parse_hex_byte(s[19]) << 0) | (parse_hex_byte(s[20]) << 4) | (parse_hex_byte(s[21]) << 8) | (parse_hex_byte(s[22]) << 12) |
0089             (parse_hex_byte(s[24]) << 16) | (parse_hex_byte(s[25]) << 20) | (parse_hex_byte(s[26]) << 24) | (parse_hex_byte(s[27]) << 28) |
0090             (parse_hex_byte(s[28]) << 32) | (parse_hex_byte(s[29]) << 36) | (parse_hex_byte(s[30]) << 40) | (parse_hex_byte(s[31]) << 44) |
0091             (parse_hex_byte(s[32]) << 48) | (parse_hex_byte(s[33]) << 52) | (parse_hex_byte(s[34]) << 56) | (parse_hex_byte(s[35]) << 60));
0092   }
0093   template <size_t N> constexpr inline unsigned long long parse_uuid_from_array(const char (&uuid)[N])
0094   {
0095     return (N == 37) ? parse_uuid2(uuid) : ((N == 39) ? parse_uuid2(uuid + 1) : BOOST_OUTCOME_SYSTEM_ERROR2_FAIL_CONSTEXPR("UUID does not have correct length"));
0096   }
0097   template <size_t N> constexpr inline unsigned long long parse_uuid_from_pointer(const char *uuid)
0098   {
0099     return (N == 36) ? parse_uuid2(uuid) : ((N == 38) ? parse_uuid2(uuid + 1) : BOOST_OUTCOME_SYSTEM_ERROR2_FAIL_CONSTEXPR("UUID does not have correct length"));
0100   }
0101 #ifdef __GNUC__
0102 #pragma GCC diagnostic pop
0103 #endif
0104   static constexpr unsigned long long test_uuid_parse = parse_uuid_from_array("430f1201-94fc-06c7-430f-120194fc06c7");
0105   // static constexpr unsigned long long test_uuid_parse2 = parse_uuid_from_array("x30f1201-94fc-06c7-430f-120194fc06c7");
0106 }  // namespace detail
0107
0108 /*! Abstract base class for a coding domain of a status code.
0109  */
0110 class status_code_domain
0111 {
0112   template <class DomainType> friend class status_code;
0113   template <class StatusCode, class Allocator> friend class detail::indirecting_domain;
0114
0115 public:
0116   //! Type of the unique id for this domain.
0117   using unique_id_type = unsigned long long;
0118   /*! (Potentially thread safe) Reference to a message string.
0119
0120   Be aware that you cannot add payload to implementations of this class.
0121   You get exactly the `void *[3]` array to keep state, this is usually
0122   sufficient for a `std::shared_ptr<>` or a `std::string`.
0123
0124   You can install a handler to be called when this object is copied,
0125   moved and destructed. This takes the form of a C function pointer.
0126   */
0127   class string_ref
0128   {
0129   public:
0130     //! The value type
0131     using value_type = const char;
0132     //! The size type
0133     using size_type = size_t;
0134     //! The pointer type
0135     using pointer = const char *;
0136     //! The const pointer type
0137     using const_pointer = const char *;
0138     //! The iterator type
0139     using iterator = const char *;
0140     //! The const iterator type
0141     using const_iterator = const char *;
0142
0143   protected:
0144     //! The operation occurring
0145     enum class _thunk_op
0146     {
0147       copy,
0148       move,
0149       destruct
0150     };
0151     //! The prototype of the handler function. Copies can throw, moves and destructs cannot.
0152     using _thunk_spec = void (*)(string_ref *dest, const string_ref *src, _thunk_op op);
0153 #ifndef NDEBUG
0154   private:
0155     static void _checking_string_thunk(string_ref *dest, const string_ref *src, _thunk_op /*unused*/) noexcept
0156     {
0157       (void) dest;
0158       (void) src;
0159       assert(dest->_thunk == _checking_string_thunk);                   // NOLINT
0160       assert(src == nullptr || src->_thunk == _checking_string_thunk);  // NOLINT
0161       // do nothing
0162     }
0163
0164   protected:
0165 #endif
0166     //! Pointers to beginning and end of character range
0167     pointer _begin{}, _end{};
0168     //! Three `void*` of state
0169     void *_state[3]{};  // at least the size of a shared_ptr
0170     //! Handler for when operations occur
0171     const _thunk_spec _thunk{nullptr};
0172
0173     constexpr explicit string_ref(_thunk_spec thunk) noexcept
0174         : _thunk(thunk)
0175     {
0176     }
0177
0178   public:
0179     //! Construct from a C string literal
0180     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR14 explicit string_ref(const char *str, size_type len = static_cast<size_type>(-1), void *state0 = nullptr, void *state1 = nullptr,
0181                                                   void *state2 = nullptr,
0182 #ifndef NDEBUG
0183                                                   _thunk_spec thunk = _checking_string_thunk
0184 #else
0185                                                   _thunk_spec thunk = nullptr
0186 #endif
0187                                                   ) noexcept
0188         : _begin(str)
0189         , _end((len == static_cast<size_type>(-1)) ? (str + detail::cstrlen(str)) : (str + len))
0190         ,  // NOLINT
0191         _state{state0, state1, state2}
0192         , _thunk(thunk)
0193     {
0194     }
0195     //! Copy construct the derived implementation.
0196     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 string_ref(const string_ref &o)
0197         : _begin(o._begin)
0198         , _end(o._end)
0199         , _state{o._state[0], o._state[1], o._state[2]}
0200         , _thunk(o._thunk)
0201     {
0202       if(_thunk != nullptr)
0203       {
0204         _thunk(this, &o, _thunk_op::copy);
0205       }
0206     }
0207     //! Move construct the derived implementation.
0208     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 string_ref(string_ref &&o) noexcept
0209         : _begin(o._begin)
0210         , _end(o._end)
0211         , _state{o._state[0], o._state[1], o._state[2]}
0212         , _thunk(o._thunk)
0213     {
0214       if(_thunk != nullptr)
0215       {
0216         _thunk(this, &o, _thunk_op::move);
0217       }
0218     }
0219     //! Copy assignment
0220     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 string_ref &operator=(const string_ref &o)
0221     {
0222       if(this != &o)
0223       {
0224 #if defined(__cpp_exceptions) || defined(__EXCEPTIONS) || defined(_CPPUNWIND)
0225         string_ref temp(static_cast<string_ref &&>(*this));
0226         this->~string_ref();
0227         try
0228         {
0229           new(this) string_ref(o);  // may throw
0230         }
0231         catch(...)
0232         {
0233           new(this) string_ref(static_cast<string_ref &&>(temp));
0234           throw;
0235         }
0236 #else
0237         this->~string_ref();
0238         new(this) string_ref(o);
0239 #endif
0240       }
0241       return *this;
0242     }
0243     //! Move assignment
0244     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 string_ref &operator=(string_ref &&o) noexcept
0245     {
0246       if(this != &o)
0247       {
0248         this->~string_ref();
0249         new(this) string_ref(static_cast<string_ref &&>(o));
0250       }
0251       return *this;
0252     }
0253     //! Destruction
0254     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 ~string_ref()
0255     {
0256       if(_thunk != nullptr)
0257       {
0258         _thunk(this, nullptr, _thunk_op::destruct);
0259       }
0260       _begin = _end = nullptr;
0261     }
0262
0263     //! Returns whether the reference is empty or not
0264     BOOST_OUTCOME_SYSTEM_ERROR2_NODISCARD constexpr bool empty() const noexcept { return _begin == _end; }
0265     //! Returns the size of the string
0266     constexpr size_type size() const noexcept { return _end - _begin; }
0267     //! Returns a null terminated C string
0268     constexpr const_pointer c_str() const noexcept { return _begin; }
0269     //! Returns a null terminated C string
0270     constexpr const_pointer data() const noexcept { return _begin; }
0271     //! Returns the beginning of the string
0272     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR14 iterator begin() noexcept { return _begin; }
0273     //! Returns the beginning of the string
0274     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR14 const_iterator begin() const noexcept { return _begin; }
0275     //! Returns the beginning of the string
0276     constexpr const_iterator cbegin() const noexcept { return _begin; }
0277     //! Returns the end of the string
0278     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR14 iterator end() noexcept { return _end; }
0279     //! Returns the end of the string
0280     BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR14 const_iterator end() const noexcept { return _end; }
0281     //! Returns the end of the string
0282     constexpr const_iterator cend() const noexcept { return _end; }
0283   };
0284
0285   /*! A reference counted, threadsafe reference to a message string.
0286    */
0287   class atomic_refcounted_string_ref : public string_ref
0288   {
0289     struct _allocated_msg
0290     {
0291       mutable std::atomic<unsigned> count{1};
0292     };
0293     _allocated_msg *&_msg() noexcept { return reinterpret_cast<_allocated_msg *&>(this->_state[0]); }                  // NOLINT
0294     const _allocated_msg *_msg() const noexcept { return reinterpret_cast<const _allocated_msg *>(this->_state[0]); }  // NOLINT
0295
0296     static BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 void _refcounted_string_thunk(string_ref *_dest, const string_ref *_src, _thunk_op op) noexcept
0297     {
0298       auto dest = static_cast<atomic_refcounted_string_ref *>(_dest);      // NOLINT
0299       auto src = static_cast<const atomic_refcounted_string_ref *>(_src);  // NOLINT
0300       (void) src;
0301       assert(dest->_thunk == _refcounted_string_thunk);                   // NOLINT
0302       assert(src == nullptr || src->_thunk == _refcounted_string_thunk);  // NOLINT
0303       switch(op)
0304       {
0305       case _thunk_op::copy:
0306       {
0307         if(dest->_msg() != nullptr)
0308         {
0309           auto count = dest->_msg()->count.fetch_add(1, std::memory_order_relaxed);
0310           (void) count;
0311           assert(count != 0);  // NOLINT
0312         }
0313         return;
0314       }
0315       case _thunk_op::move:
0316       {
0317         assert(src);                                                  // NOLINT
0318         auto msrc = const_cast<atomic_refcounted_string_ref *>(src);  // NOLINT
0319         msrc->_begin = msrc->_end = nullptr;
0320         msrc->_state[0] = msrc->_state[1] = msrc->_state[2] = nullptr;
0321         return;
0322       }
0323       case _thunk_op::destruct:
0324       {
0325         if(dest->_msg() != nullptr)
0326         {
0327           auto count = dest->_msg()->count.fetch_sub(1, std::memory_order_release);
0328           if(count == 1)
0329           {
0330             std::atomic_thread_fence(std::memory_order_acquire);
0331             free((void *) dest->_begin);  // NOLINT
0332             delete dest->_msg();          // NOLINT
0333           }
0334         }
0335       }
0336       }
0337     }
0338
0339   public:
0340     //! Construct from a C string literal allocated using `malloc()`.
0341     explicit atomic_refcounted_string_ref(const char *str, size_type len = static_cast<size_type>(-1), void *state1 = nullptr, void *state2 = nullptr) noexcept
0342         : string_ref(str, len, new(std::nothrow) _allocated_msg, state1, state2, _refcounted_string_thunk)
0343     {
0344       if(_msg() == nullptr)
0345       {
0346         free((void *) this->_begin);  // NOLINT
0347         _msg() = nullptr;             // disabled
0348         this->_begin = "failed to get message from system";
0349         this->_end = strchr(this->_begin, 0);
0350         return;
0351       }
0352     }
0353   };
0354
0355 private:
0356   unique_id_type _id;
0357
0358 protected:
0359   /*! Use [https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h](https://www.random.org/cgi-bin/randbyte?nbytes=8&format=h) to get a random 64 bit id.
0360
0361   Do NOT make up your own value. Do NOT use zero.
0362   */
0363   constexpr explicit status_code_domain(unique_id_type id) noexcept
0364       : _id(id)
0365   {
0366   }
0367   /*! UUID constructor, where input is constexpr parsed into a `unique_id_type`.
0368    */
0369   template <size_t N>
0370   constexpr explicit status_code_domain(const char (&uuid)[N]) noexcept
0371       : _id(detail::parse_uuid_from_array<N>(uuid))
0372   {
0373   }
0374   template <size_t N> struct _uuid_size
0375   {
0376   };
0377   //! Alternative UUID constructor
0378   template <size_t N>
0379   constexpr explicit status_code_domain(const char *uuid, _uuid_size<N> /*unused*/) noexcept
0380       : _id(detail::parse_uuid_from_pointer<N>(uuid))
0381   {
0382   }
0383   //! No public copying at type erased level
0384   status_code_domain(const status_code_domain &) = default;
0385   //! No public moving at type erased level
0386   status_code_domain(status_code_domain &&) = default;
0387   //! No public assignment at type erased level
0388   status_code_domain &operator=(const status_code_domain &) = default;
0389   //! No public assignment at type erased level
0390   status_code_domain &operator=(status_code_domain &&) = default;
0391   //! No public destruction at type erased level
0392   ~status_code_domain() = default;
0393
0394 public:
0395   //! True if the unique ids match.
0396   constexpr bool operator==(const status_code_domain &o) const noexcept { return _id == o._id; }
0397   //! True if the unique ids do not match.
0398   constexpr bool operator!=(const status_code_domain &o) const noexcept { return _id != o._id; }
0399   //! True if this unique is lower than the other's unique id.
0400   constexpr bool operator<(const status_code_domain &o) const noexcept { return _id < o._id; }
0401
0402   //! Returns the unique id used to identify identical category instances.
0403   constexpr unique_id_type id() const noexcept { return _id; }
0404   //! Name of this category.
0405   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual string_ref name() const noexcept = 0;
0406   //! Information about the payload of the code for this domain
0407   struct payload_info_t
0408   {
0409     size_t payload_size{0};     //!< The payload size in bytes
0410     size_t total_size{0};       //!< The total status code size in bytes (includes domain pointer and mixins state)
0411     size_t total_alignment{1};  //!< The total status code alignment in bytes
0412
0413     payload_info_t() = default;
0414     constexpr payload_info_t(size_t _payload_size, size_t _total_size, size_t _total_alignment)
0415         : payload_size(_payload_size)
0416         , total_size(_total_size)
0417         , total_alignment(_total_alignment)
0418     {
0419     }
0420   };
0421   //! Information about this domain's payload
0422   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual payload_info_t payload_info() const noexcept = 0;
0423
0424 protected:
0425   //! True if code means failure.
0426   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual bool _do_failure(const status_code<void> &code) const noexcept = 0;
0427   //! True if code is (potentially non-transitively) equivalent to another code in another domain.
0428   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual bool _do_equivalent(const status_code<void> &code1, const status_code<void> &code2) const noexcept = 0;
0429   //! Returns the generic code closest to this code, if any.
0430   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual generic_code _generic_code(const status_code<void> &code) const noexcept = 0;
0431   //! Return a reference to a string textually representing a code.
0432   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual string_ref _do_message(const status_code<void> &code) const noexcept = 0;
0433 #if defined(_CPPUNWIND) || defined(__EXCEPTIONS) || defined(BOOST_OUTCOME_STANDARDESE_IS_IN_THE_HOUSE)
0434   //! Throw a code as a C++ exception.
0435   BOOST_OUTCOME_SYSTEM_ERROR2_NORETURN BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual void _do_throw_exception(const status_code<void> &code) const = 0;
0436 #else
0437   // Keep a vtable slot for binary compatibility
0438   BOOST_OUTCOME_SYSTEM_ERROR2_NORETURN virtual void _do_throw_exception(const status_code<void> & /*code*/) const { abort(); }
0439 #endif
0440   // For a `status_code<erased<T>>` only, copy from `src` to `dst`. Default implementation uses `memcpy()`. You should return false here if your payload is not
0441   // trivially copyable or would not fit.
0442   virtual bool _do_erased_copy(status_code<void> &dst, const status_code<void> &src, payload_info_t dstinfo) const
0443   {
0444     // Note that dst may not have its domain set
0445     const auto srcinfo = payload_info();
0446     if(dstinfo.total_size < srcinfo.total_size)
0447     {
0448       return false;
0449     }
0450     const auto tocopy = (dstinfo.total_size > srcinfo.total_size) ? srcinfo.total_size : dstinfo.total_size;
0451     memcpy(&dst, &src, tocopy);
0452     return true;
0453   }  // NOLINT
0454   // For a `status_code<erased<T>>` only, destroy the erased value type. Default implementation does nothing.
0455   BOOST_OUTCOME_SYSTEM_ERROR2_CONSTEXPR20 virtual void _do_erased_destroy(status_code<void> &code, payload_info_t info) const noexcept  // NOLINT
0456   {
0457     (void) code;
0458     (void) info;
0459   }
0460 };
0461
0462 BOOST_OUTCOME_SYSTEM_ERROR2_NAMESPACE_END
0463
0464 #endif