1 // 2 // 3 // Copyright 2021 the gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // You may obtain a copy of the License at 8 // 9 // http://www.apache.org/licenses/LICENSE-2.0 10 // 11 // Unless required by applicable law or agreed to in writing, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 // 17 // 18 19 #ifndef GRPC_CORE_LIB_GPRPP_STATUS_HELPER_H 20 #define GRPC_CORE_LIB_GPRPP_STATUS_HELPER_H 21 22 #include <grpc/support/port_platform.h> 23 24 #include "absl/status/status.h" 25 #include "absl/time/time.h" 26 27 #include "src/core/lib/gprpp/debug_location.h" 28 29 extern "C" { 30 struct google_rpc_Status; 31 struct upb_arena; 32 } 33 34 namespace grpc_core { 35 36 /// This enum should have the same value of grpc_error_ints 37 // TODO(veblush): Use camel-case names once migration to absl::Status is done. 38 enum class StatusIntProperty { 39 /// 'errno' from the operating system 40 kErrorNo, 41 /// __LINE__ from the call site creating the error 42 kFileLine, 43 /// stream identifier: for errors that are associated with an individual 44 /// wire stream 45 kStreamId, 46 /// grpc status code representing this error 47 // TODO(veblush): Remove this after grpc_error is replaced with absl::Status 48 kRpcStatus, 49 /// offset into some binary blob (usually represented by 50 /// RAW_BYTES) where the error occurred 51 kOffset, 52 /// context sensitive index associated with the error 53 kIndex, 54 /// context sensitive size associated with the error 55 kSize, 56 /// http2 error code associated with the error (see the HTTP2 RFC) 57 kHttp2Error, 58 /// TSI status code associated with the error 59 kTsiCode, 60 /// WSAGetLastError() reported when this error occurred 61 kWsaError, 62 /// File descriptor associated with this error 63 kFd, 64 /// HTTP status (i.e. 404) 65 kHttpStatus, 66 /// chttp2: did the error occur while a write was in progress 67 kOccurredDuringWrite, 68 /// channel connectivity state associated with the error 69 ChannelConnectivityState, 70 /// LB policy drop 71 kLbPolicyDrop, 72 }; 73 74 /// This enum should have the same value of grpc_error_strs 75 // TODO(veblush): Use camel-case names once migration to absl::Status is done. 76 enum class StatusStrProperty { 77 /// top-level textual description of this error 78 kDescription, 79 /// source file in which this error occurred 80 kFile, 81 /// operating system description of this error 82 kOsError, 83 /// syscall that generated this error 84 kSyscall, 85 /// peer that we were trying to communicate when this error occurred 86 kTargetAddress, 87 /// grpc status message associated with this error 88 kGrpcMessage, 89 /// hex dump (or similar) with the data that generated this error 90 kRawBytes, 91 /// tsi error string associated with this error 92 kTsiError, 93 /// filename that we were trying to read/write when this error occurred 94 kFilename, 95 /// key associated with the error 96 kKey, 97 /// value associated with the error 98 kValue, 99 }; 100 101 /// This enum should have the same value of grpc_error_times 102 enum class StatusTimeProperty { 103 /// timestamp of error creation 104 kCreated, 105 }; 106 107 /// Creates a status with given additional information 108 absl::Status StatusCreate( 109 absl::StatusCode code, absl::string_view msg, const DebugLocation& location, 110 std::initializer_list<absl::Status> children) GRPC_MUST_USE_RESULT; 111 112 /// Sets the int property to the status 113 void StatusSetInt(absl::Status* status, StatusIntProperty key, intptr_t value); 114 115 /// Gets the int property from the status 116 absl::optional<intptr_t> StatusGetInt( 117 const absl::Status& status, StatusIntProperty key) GRPC_MUST_USE_RESULT; 118 119 /// Sets the str property to the status 120 void StatusSetStr(absl::Status* status, StatusStrProperty key, 121 absl::string_view value); 122 123 /// Gets the str property from the status 124 absl::optional<std::string> StatusGetStr( 125 const absl::Status& status, StatusStrProperty key) GRPC_MUST_USE_RESULT; 126 127 /// Sets the time property to the status 128 void StatusSetTime(absl::Status* status, StatusTimeProperty key, 129 absl::Time time); 130 131 /// Gets the time property from the status 132 absl::optional<absl::Time> StatusGetTime( 133 const absl::Status& status, StatusTimeProperty key) GRPC_MUST_USE_RESULT; 134 135 /// Adds a child status to status 136 void StatusAddChild(absl::Status* status, absl::Status child); 137 138 /// Returns all children status from a status 139 std::vector<absl::Status> StatusGetChildren(absl::Status status) 140 GRPC_MUST_USE_RESULT; 141 142 /// Returns a string representation from status 143 /// Error status will be like 144 /// STATUS[:MESSAGE] [{PAYLOADS[, children:[CHILDREN-STATUS-LISTS]]}] 145 /// e.g. 146 /// CANCELLATION:SampleMessage {errno:'2021', line:'54', children:[ABORTED]} 147 std::string StatusToString(const absl::Status& status) GRPC_MUST_USE_RESULT; 148 149 namespace internal { 150 151 /// Builds a upb message, google_rpc_Status from a status 152 /// This is for internal implementation & test only 153 google_rpc_Status* StatusToProto(absl::Status status, 154 upb_arena* arena) GRPC_MUST_USE_RESULT; 155 156 /// Builds a status from a upb message, google_rpc_Status 157 /// This is for internal implementation & test only 158 absl::Status StatusFromProto(google_rpc_Status* msg) GRPC_MUST_USE_RESULT; 159 160 /// The same value of grpc_core::internal::StatusAllocPtr(absl::OkStatus()) 161 static constexpr uintptr_t kOkStatusPtr = 0; 162 163 /// Returns ptr where the given status is copied into. 164 /// This ptr can be used to get Status later and should be freed by 165 /// StatusFreePtr. This shouldn't be used except migration purpose. 166 uintptr_t StatusAllocPtr(absl::Status s); 167 168 /// Frees the allocated status at ptr. 169 /// This shouldn't be used except migration purpose. 170 void StatusFreePtr(uintptr_t ptr); 171 172 /// Get the status from ptr. 173 /// This shouldn't be used except migration purpose. 174 absl::Status StatusGetFromPtr(uintptr_t ptr); 175 176 } // namespace internal 177 178 } // namespace grpc_core 179 180 #endif // GRPC_CORE_LIB_GPRPP_STATUS_HELPER_H 181