Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 1 | /* |
| 2 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 3 | * Copyright 2016 gRPC authors. |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 4 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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 |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 8 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 9 | * http://www.apache.org/licenses/LICENSE-2.0 |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 10 | * |
Jan Tattermusch | 7897ae9 | 2017-06-07 22:57:36 +0200 | [diff] [blame] | 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. |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 16 | * |
| 17 | */ |
| 18 | |
| 19 | #ifndef GRPC_CORE_LIB_IOMGR_ERROR_H |
| 20 | #define GRPC_CORE_LIB_IOMGR_ERROR_H |
| 21 | |
Craig Tiller | 4f1d0f3 | 2016-05-06 17:12:37 -0700 | [diff] [blame] | 22 | #include <stdbool.h> |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 23 | #include <stdint.h> |
| 24 | |
ncteisen | bbb3801 | 2017-03-10 14:58:43 -0800 | [diff] [blame] | 25 | #include <grpc/slice.h> |
Mark D. Roth | 1e35b69 | 2016-09-02 13:44:32 -0700 | [diff] [blame] | 26 | #include <grpc/status.h> |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 27 | #include <grpc/support/time.h> |
| 28 | |
ncteisen | f0c46e3 | 2017-06-08 15:57:09 -0700 | [diff] [blame] | 29 | #include "src/core/lib/debug/trace.h" |
| 30 | |
Mark D. Roth | 757e84e | 2016-10-06 13:07:53 -0700 | [diff] [blame] | 31 | #ifdef __cplusplus |
| 32 | extern "C" { |
| 33 | #endif |
| 34 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 35 | /// Opaque representation of an error. |
ncteisen | 031cfeb | 2017-03-21 19:07:17 -0700 | [diff] [blame] | 36 | /// See https://github.com/grpc/grpc/blob/master/doc/core/grpc-error.md for a |
| 37 | /// full write up of this object. |
| 38 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 39 | typedef struct grpc_error grpc_error; |
| 40 | |
ncteisen | a135485 | 2017-06-08 16:25:53 -0700 | [diff] [blame] | 41 | #ifndef NDEBUG |
ncteisen | f0c46e3 | 2017-06-08 15:57:09 -0700 | [diff] [blame] | 42 | extern grpc_tracer_flag grpc_trace_error_refcount; |
ncteisen | a135485 | 2017-06-08 16:25:53 -0700 | [diff] [blame] | 43 | #endif |
ncteisen | f0c46e3 | 2017-06-08 15:57:09 -0700 | [diff] [blame] | 44 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 45 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 46 | /// 'errno' from the operating system |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 47 | GRPC_ERROR_INT_ERRNO, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 48 | /// __LINE__ from the call site creating the error |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 49 | GRPC_ERROR_INT_FILE_LINE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 50 | /// stream identifier: for errors that are associated with an individual |
| 51 | /// wire stream |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 52 | GRPC_ERROR_INT_STREAM_ID, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 53 | /// grpc status code representing this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 54 | GRPC_ERROR_INT_GRPC_STATUS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 55 | /// offset into some binary blob (usually represented by |
| 56 | /// GRPC_ERROR_STR_RAW_BYTES) where the error occurred |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 57 | GRPC_ERROR_INT_OFFSET, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 58 | /// context sensitive index associated with the error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 59 | GRPC_ERROR_INT_INDEX, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 60 | /// context sensitive size associated with the error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 61 | GRPC_ERROR_INT_SIZE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 62 | /// http2 error code associated with the error (see the HTTP2 RFC) |
Craig Tiller | 94e1576 | 2016-05-05 08:44:36 -0700 | [diff] [blame] | 63 | GRPC_ERROR_INT_HTTP2_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 64 | /// TSI status code associated with the error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 65 | GRPC_ERROR_INT_TSI_CODE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 66 | /// grpc_security_status associated with the error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 67 | GRPC_ERROR_INT_SECURITY_STATUS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 68 | /// WSAGetLastError() reported when this error occurred |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 69 | GRPC_ERROR_INT_WSA_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 70 | /// File descriptor associated with this error |
Craig Tiller | 80384bd | 2016-05-06 16:12:31 -0700 | [diff] [blame] | 71 | GRPC_ERROR_INT_FD, |
Craig Tiller | 34b11df | 2016-06-09 17:17:15 -0700 | [diff] [blame] | 72 | /// HTTP status (i.e. 404) |
| 73 | GRPC_ERROR_INT_HTTP_STATUS, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 74 | /// context sensitive limit associated with the error |
| 75 | GRPC_ERROR_INT_LIMIT, |
Craig Tiller | 936f1ea | 2016-10-14 15:15:19 -0700 | [diff] [blame] | 76 | /// chttp2: did the error occur while a write was in progress |
| 77 | GRPC_ERROR_INT_OCCURRED_DURING_WRITE, |
ncteisen | 55337bb | 2017-03-02 15:12:33 -0800 | [diff] [blame] | 78 | |
| 79 | /// Must always be last |
| 80 | GRPC_ERROR_INT_MAX, |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 81 | } grpc_error_ints; |
| 82 | |
| 83 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 84 | /// top-level textual description of this error |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 85 | GRPC_ERROR_STR_DESCRIPTION, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 86 | /// source file in which this error occurred |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 87 | GRPC_ERROR_STR_FILE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 88 | /// operating system description of this error |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 89 | GRPC_ERROR_STR_OS_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 90 | /// syscall that generated this error |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 91 | GRPC_ERROR_STR_SYSCALL, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 92 | /// peer that we were trying to communicate when this error occurred |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 93 | GRPC_ERROR_STR_TARGET_ADDRESS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 94 | /// grpc status message associated with this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 95 | GRPC_ERROR_STR_GRPC_MESSAGE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 96 | /// hex dump (or similar) with the data that generated this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 97 | GRPC_ERROR_STR_RAW_BYTES, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 98 | /// tsi error string associated with this error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 99 | GRPC_ERROR_STR_TSI_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 100 | /// filename that we were trying to read/write when this error occurred |
Craig Tiller | 4727b9b | 2016-05-17 17:19:19 -0700 | [diff] [blame] | 101 | GRPC_ERROR_STR_FILENAME, |
Craig Tiller | 936f1ea | 2016-10-14 15:15:19 -0700 | [diff] [blame] | 102 | /// which data was queued for writing when the error occurred |
Craig Tiller | 7c70b6c | 2017-01-23 07:48:42 -0800 | [diff] [blame] | 103 | GRPC_ERROR_STR_QUEUED_BUFFERS, |
| 104 | /// key associated with the error |
| 105 | GRPC_ERROR_STR_KEY, |
| 106 | /// value associated with the error |
| 107 | GRPC_ERROR_STR_VALUE, |
ncteisen | 55337bb | 2017-03-02 15:12:33 -0800 | [diff] [blame] | 108 | |
| 109 | /// Must always be last |
| 110 | GRPC_ERROR_STR_MAX, |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 111 | } grpc_error_strs; |
| 112 | |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 113 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 114 | /// timestamp of error creation |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 115 | GRPC_ERROR_TIME_CREATED, |
ncteisen | 55337bb | 2017-03-02 15:12:33 -0800 | [diff] [blame] | 116 | |
| 117 | /// Must always be last |
| 118 | GRPC_ERROR_TIME_MAX, |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 119 | } grpc_error_times; |
| 120 | |
Craig Tiller | 86037cd0 | 2016-09-02 19:58:43 -0700 | [diff] [blame] | 121 | /// The following "special" errors can be propagated without allocating memory. |
Sree Kuchibhotla | 2fc2b3e | 2017-02-14 10:05:14 -0800 | [diff] [blame] | 122 | /// They are always even so that other code (particularly combiner locks, |
| 123 | /// polling engines) can safely use the lower bit for themselves. |
Craig Tiller | 86037cd0 | 2016-09-02 19:58:43 -0700 | [diff] [blame] | 124 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 125 | #define GRPC_ERROR_NONE ((grpc_error *)NULL) |
Craig Tiller | 86037cd0 | 2016-09-02 19:58:43 -0700 | [diff] [blame] | 126 | #define GRPC_ERROR_OOM ((grpc_error *)2) |
| 127 | #define GRPC_ERROR_CANCELLED ((grpc_error *)4) |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 128 | |
| 129 | const char *grpc_error_string(grpc_error *error); |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 130 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 131 | /// Create an error - but use GRPC_ERROR_CREATE instead |
Noah Eisen | f88ee4f | 2017-04-17 18:14:39 -0700 | [diff] [blame] | 132 | grpc_error *grpc_error_create(const char *file, int line, grpc_slice desc, |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 133 | grpc_error **referencing, size_t num_referencing); |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 134 | /// Create an error (this is the preferred way of generating an error that is |
| 135 | /// not due to a system call - for system calls, use GRPC_OS_ERROR or |
| 136 | /// GRPC_WSA_ERROR as appropriate) |
| 137 | /// \a referencing is an array of num_referencing elements indicating one or |
| 138 | /// more errors that are believed to have contributed to this one |
| 139 | /// err = grpc_error_create(x, y, z, r, nr) is equivalent to: |
| 140 | /// err = grpc_error_create(x, y, z, NULL, 0); |
| 141 | /// for (i=0; i<nr; i++) err = grpc_error_add_child(err, r[i]); |
Noah Eisen | f88ee4f | 2017-04-17 18:14:39 -0700 | [diff] [blame] | 142 | #define GRPC_ERROR_CREATE_FROM_STATIC_STRING(desc) \ |
| 143 | grpc_error_create(__FILE__, __LINE__, grpc_slice_from_static_string(desc), \ |
| 144 | NULL, 0) |
| 145 | #define GRPC_ERROR_CREATE_FROM_COPIED_STRING(desc) \ |
| 146 | grpc_error_create(__FILE__, __LINE__, grpc_slice_from_copied_string(desc), \ |
| 147 | NULL, 0) |
ncteisen | bbb3801 | 2017-03-10 14:58:43 -0800 | [diff] [blame] | 148 | |
David Garcia Quintas | 32ec133 | 2016-05-11 12:22:53 -0700 | [diff] [blame] | 149 | // Create an error that references some other errors. This function adds a |
| 150 | // reference to each error in errs - it does not consume an existing reference |
Noah Eisen | f88ee4f | 2017-04-17 18:14:39 -0700 | [diff] [blame] | 151 | #define GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING(desc, errs, count) \ |
| 152 | grpc_error_create(__FILE__, __LINE__, grpc_slice_from_static_string(desc), \ |
| 153 | errs, count) |
| 154 | #define GRPC_ERROR_CREATE_REFERENCING_FROM_COPIED_STRING(desc, errs, count) \ |
| 155 | grpc_error_create(__FILE__, __LINE__, grpc_slice_from_copied_string(desc), \ |
| 156 | errs, count) |
Craig Tiller | f707d62 | 2016-05-06 14:26:12 -0700 | [diff] [blame] | 157 | |
ncteisen | f0c46e3 | 2017-06-08 15:57:09 -0700 | [diff] [blame] | 158 | #ifndef NDEBUG |
ncteisen | d39010e | 2017-06-08 17:08:07 -0700 | [diff] [blame] | 159 | grpc_error *grpc_error_ref(grpc_error *err, const char *file, int line); |
| 160 | void grpc_error_unref(grpc_error *err, const char *file, int line); |
| 161 | #define GRPC_ERROR_REF(err) grpc_error_ref(err, __FILE__, __LINE__) |
| 162 | #define GRPC_ERROR_UNREF(err) grpc_error_unref(err, __FILE__, __LINE__) |
Craig Tiller | e0d6c57 | 2016-05-13 07:23:36 -0700 | [diff] [blame] | 163 | #else |
| 164 | grpc_error *grpc_error_ref(grpc_error *err); |
| 165 | void grpc_error_unref(grpc_error *err); |
| 166 | #define GRPC_ERROR_REF(err) grpc_error_ref(err) |
| 167 | #define GRPC_ERROR_UNREF(err) grpc_error_unref(err) |
| 168 | #endif |
Craig Tiller | f707d62 | 2016-05-06 14:26:12 -0700 | [diff] [blame] | 169 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 170 | grpc_error *grpc_error_set_int(grpc_error *src, grpc_error_ints which, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 171 | intptr_t value) GRPC_MUST_USE_RESULT; |
Craig Tiller | 965eab3 | 2016-05-07 22:11:37 -0700 | [diff] [blame] | 172 | bool grpc_error_get_int(grpc_error *error, grpc_error_ints which, intptr_t *p); |
ncteisen | 4b36a3d | 2017-03-13 19:08:06 -0700 | [diff] [blame] | 173 | grpc_error *grpc_error_set_str(grpc_error *src, grpc_error_strs which, |
| 174 | grpc_slice str) GRPC_MUST_USE_RESULT; |
ncteisen | bbb3801 | 2017-03-10 14:58:43 -0800 | [diff] [blame] | 175 | /// Returns false if the specified string is not set. |
| 176 | /// Caller does NOT own the slice. |
ncteisen | 4b36a3d | 2017-03-13 19:08:06 -0700 | [diff] [blame] | 177 | bool grpc_error_get_str(grpc_error *error, grpc_error_strs which, |
| 178 | grpc_slice *s); |
Mark D. Roth | 1e35b69 | 2016-09-02 13:44:32 -0700 | [diff] [blame] | 179 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 180 | /// Add a child error: an error that is believed to have contributed to this |
| 181 | /// error occurring. Allows root causing high level errors from lower level |
| 182 | /// errors that contributed to them. |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 183 | grpc_error *grpc_error_add_child(grpc_error *src, |
| 184 | grpc_error *child) GRPC_MUST_USE_RESULT; |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 185 | grpc_error *grpc_os_error(const char *file, int line, int err, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 186 | const char *call_name) GRPC_MUST_USE_RESULT; |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 187 | /// create an error associated with errno!=0 (an 'operating system' error) |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 188 | #define GRPC_OS_ERROR(err, call_name) \ |
| 189 | grpc_os_error(__FILE__, __LINE__, err, call_name) |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 190 | grpc_error *grpc_wsa_error(const char *file, int line, int err, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 191 | const char *call_name) GRPC_MUST_USE_RESULT; |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 192 | /// windows only: create an error associated with WSAGetLastError()!=0 |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 193 | #define GRPC_WSA_ERROR(err, call_name) \ |
| 194 | grpc_wsa_error(__FILE__, __LINE__, err, call_name) |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 195 | |
Craig Tiller | 4f1d0f3 | 2016-05-06 17:12:37 -0700 | [diff] [blame] | 196 | bool grpc_log_if_error(const char *what, grpc_error *error, const char *file, |
| 197 | int line); |
| 198 | #define GRPC_LOG_IF_ERROR(what, error) \ |
| 199 | grpc_log_if_error((what), (error), __FILE__, __LINE__) |
| 200 | |
Mark D. Roth | 757e84e | 2016-10-06 13:07:53 -0700 | [diff] [blame] | 201 | #ifdef __cplusplus |
| 202 | } |
| 203 | #endif |
| 204 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 205 | #endif /* GRPC_CORE_LIB_IOMGR_ERROR_H */ |