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