TLA  Line data    Source code

       1                 : //
       2                 : // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
       3                 : // Copyright (c) 2026 Michael Vandeberg
       4                 : //
       5                 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
       6                 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
       7                 : //
       8                 : // Official repository: https://github.com/cppalliance/capy
       9                 : //
      10                 : 
      11                 : #ifndef BOOST_CAPY_COND_HPP
      12                 : #define BOOST_CAPY_COND_HPP
      13                 : 
      14                 : #include <boost/capy/detail/config.hpp>
      15                 : #include <system_error>
      16                 : 
      17                 : namespace boost {
      18                 : namespace capy {
      19                 : 
      20                 : /** Portable error conditions for capy I/O operations.
      21                 : 
      22                 :     These are the conditions callers should compare against when
      23                 :     handling errors from capy operations. The @ref error enum values
      24                 :     map to these conditions, as do platform-specific error codes
      25                 :     (e.g., `ECANCELED`, SSL EOF errors).
      26                 : 
      27                 :     @par Example
      28                 : 
      29                 :     @code
      30                 :     auto [ec, n] = co_await stream.read_some( bufs );
      31                 :     if( ec == cond::canceled )
      32                 :     {
      33                 :         // handle cancellation
      34                 :     }
      35                 :     else if( ec == cond::eof )
      36                 :     {
      37                 :         // handle end of stream
      38                 :     }
      39                 :     else if( ec )
      40                 :     {
      41                 :         // handle other errors
      42                 :     }
      43                 :     @endcode
      44                 : 
      45                 :     @see error
      46                 : */
      47                 : enum class cond
      48                 : {
      49                 :     /** End-of-stream condition.
      50                 : 
      51                 :         An `error_code` compares equal to `eof` when the stream
      52                 :         reached its natural end. Examples are a peer sending TCP
      53                 :         FIN, or a file reaching EOF.
      54                 :     */
      55                 :     eof = 1,
      56                 : 
      57                 :     /** Operation cancelled condition.
      58                 : 
      59                 :         An `error_code` compares equal to `canceled` when the
      60                 :         operation's stop token was activated, the I/O object's
      61                 :         `cancel()` was called, or a platform cancellation error
      62                 :         occurred.
      63                 :     */
      64                 :     canceled = 2,
      65                 : 
      66                 :     /** Stream truncated condition.
      67                 : 
      68                 :         An `error_code` compares equal to `stream_truncated` when
      69                 :         a TLS peer closed the connection without sending a proper
      70                 :         shutdown alert.
      71                 :     */
      72                 :     stream_truncated = 3,
      73                 : 
      74                 :     /** Operation timed out condition.
      75                 : 
      76                 :         An `error_code` compares equal to `timeout` when an
      77                 :         operation exceeded its allowed duration.
      78                 :     */
      79                 :     timeout = 4
      80                 : };
      81                 : 
      82                 : } // capy
      83                 : } // boost
      84                 : 
      85                 : namespace std {
      86                 : template<>
      87                 : struct is_error_condition_enum<
      88                 :     ::boost::capy::cond>
      89                 :     : std::true_type {};
      90                 : } // std
      91                 : 
      92                 : namespace boost {
      93                 : namespace capy {
      94                 : 
      95                 : namespace detail {
      96                 : 
      97                 : struct BOOST_CAPY_SYMBOL_VISIBLE
      98                 :     cond_cat_type
      99                 :     : std::error_category
     100                 : {
     101                 :     BOOST_CAPY_DECL const char* name(
     102                 :         ) const noexcept override;
     103                 :     BOOST_CAPY_DECL std::string message(
     104                 :         int) const override;
     105                 :     BOOST_CAPY_DECL bool equivalent(
     106                 :         std::error_code const& ec,
     107                 :         int condition) const noexcept override;
     108                 :     constexpr cond_cat_type() noexcept = default;
     109                 : };
     110                 : 
     111                 : BOOST_CAPY_DECL extern cond_cat_type cond_cat;
     112                 : 
     113                 : } // detail
     114                 : 
     115                 : /** Create an error_condition from a cond value.
     116                 : 
     117                 :     @param ev The library condition value.
     118                 : 
     119                 :     @return An `std::error_condition` holding `ev` in the library's
     120                 :         condition category.
     121                 : */
     122                 : inline
     123                 : std::error_condition
     124 HIT         227 : make_error_condition(
     125                 :     cond ev) noexcept
     126                 : {
     127             227 :     return std::error_condition{
     128                 :         static_cast<std::underlying_type<
     129                 :             cond>::type>(ev),
     130             227 :         detail::cond_cat};
     131                 : }
     132                 : 
     133                 : } // capy
     134                 : } // boost
     135                 : 
     136                 : #endif