Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 1 | /* |
| 2 | * |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 3 | * Copyright 2016, Google Inc. |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 4 | * All rights reserved. |
| 5 | * |
| 6 | * Redistribution and use in source and binary forms, with or without |
| 7 | * modification, are permitted provided that the following conditions are |
| 8 | * met: |
| 9 | * |
| 10 | * * Redistributions of source code must retain the above copyright |
| 11 | * notice, this list of conditions and the following disclaimer. |
| 12 | * * Redistributions in binary form must reproduce the above |
| 13 | * copyright notice, this list of conditions and the following disclaimer |
| 14 | * in the documentation and/or other materials provided with the |
| 15 | * distribution. |
| 16 | * * Neither the name of Google Inc. nor the names of its |
| 17 | * contributors may be used to endorse or promote products derived from |
| 18 | * this software without specific prior written permission. |
| 19 | * |
| 20 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
| 21 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
| 22 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
| 23 | * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
| 24 | * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| 25 | * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| 26 | * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
| 27 | * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
| 28 | * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
| 29 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
| 30 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| 31 | * |
| 32 | */ |
| 33 | |
| 34 | #ifndef GRPC_CORE_LIB_IOMGR_ERROR_H |
| 35 | #define GRPC_CORE_LIB_IOMGR_ERROR_H |
| 36 | |
Craig Tiller | 4f1d0f3 | 2016-05-06 17:12:37 -0700 | [diff] [blame] | 37 | #include <stdbool.h> |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 38 | #include <stdint.h> |
| 39 | |
Mark D. Roth | 1e35b69 | 2016-09-02 13:44:32 -0700 | [diff] [blame] | 40 | #include <grpc/status.h> |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 41 | #include <grpc/support/time.h> |
| 42 | |
Mark D. Roth | 757e84e | 2016-10-06 13:07:53 -0700 | [diff] [blame] | 43 | #ifdef __cplusplus |
| 44 | extern "C" { |
| 45 | #endif |
| 46 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 47 | /// Opaque representation of an error. |
| 48 | /// Errors are refcounted objects that represent the result of an operation. |
| 49 | /// Ownership laws: |
| 50 | /// if a grpc_error is returned by a function, the caller owns a ref to that |
| 51 | /// instance |
| 52 | /// if a grpc_error is passed to a grpc_closure callback function (functions |
| 53 | /// with the signature: |
| 54 | /// void (*f)(grpc_exec_ctx *exec_ctx, void *arg, grpc_error *error)) |
David Garcia Quintas | 4bf00c9 | 2016-08-19 12:39:10 -0700 | [diff] [blame] | 55 | /// then those functions do not own a ref to error (but are free to manually |
| 56 | /// take a reference). |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 57 | /// if a grpc_error is passed to *ANY OTHER FUNCTION* then that function takes |
| 58 | /// ownership of the error |
| 59 | /// Errors have: |
| 60 | /// a set of ints, strings, and timestamps that describe the error |
| 61 | /// always present are: |
| 62 | /// GRPC_ERROR_STR_FILE, GRPC_ERROR_INT_FILE_LINE - source location the error |
| 63 | /// was generated |
| 64 | /// GRPC_ERROR_STR_DESCRIPTION - a human readable description of the error |
| 65 | /// GRPC_ERROR_TIME_CREATED - a timestamp indicating when the error happened |
| 66 | /// an error can also have children; these are other errors that are believed |
| 67 | /// to have contributed to this one. By accumulating children, we can begin |
| 68 | /// to root cause high level failures from low level failures, without having |
| 69 | /// to derive execution paths from log lines |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 70 | typedef struct grpc_error grpc_error; |
| 71 | |
| 72 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 73 | /// 'errno' from the operating system |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 74 | GRPC_ERROR_INT_ERRNO, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 75 | /// __LINE__ from the call site creating the error |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 76 | GRPC_ERROR_INT_FILE_LINE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 77 | /// stream identifier: for errors that are associated with an individual |
| 78 | /// wire stream |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 79 | GRPC_ERROR_INT_STREAM_ID, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 80 | /// grpc status code representing this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 81 | GRPC_ERROR_INT_GRPC_STATUS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 82 | /// offset into some binary blob (usually represented by |
| 83 | /// GRPC_ERROR_STR_RAW_BYTES) where the error occurred |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 84 | GRPC_ERROR_INT_OFFSET, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 85 | /// context sensitive index associated with the error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 86 | GRPC_ERROR_INT_INDEX, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 87 | /// context sensitive size associated with the error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 88 | GRPC_ERROR_INT_SIZE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 89 | /// http2 error code associated with the error (see the HTTP2 RFC) |
Craig Tiller | 94e1576 | 2016-05-05 08:44:36 -0700 | [diff] [blame] | 90 | GRPC_ERROR_INT_HTTP2_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 91 | /// TSI status code associated with the error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 92 | GRPC_ERROR_INT_TSI_CODE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 93 | /// grpc_security_status associated with the error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 94 | GRPC_ERROR_INT_SECURITY_STATUS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 95 | /// WSAGetLastError() reported when this error occurred |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 96 | GRPC_ERROR_INT_WSA_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 97 | /// File descriptor associated with this error |
Craig Tiller | 80384bd | 2016-05-06 16:12:31 -0700 | [diff] [blame] | 98 | GRPC_ERROR_INT_FD, |
Craig Tiller | 34b11df | 2016-06-09 17:17:15 -0700 | [diff] [blame] | 99 | /// HTTP status (i.e. 404) |
| 100 | GRPC_ERROR_INT_HTTP_STATUS, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 101 | /// context sensitive limit associated with the error |
| 102 | GRPC_ERROR_INT_LIMIT, |
Craig Tiller | 936f1ea | 2016-10-14 15:15:19 -0700 | [diff] [blame] | 103 | /// chttp2: did the error occur while a write was in progress |
| 104 | GRPC_ERROR_INT_OCCURRED_DURING_WRITE, |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 105 | } grpc_error_ints; |
| 106 | |
| 107 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 108 | /// top-level textual description of this error |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 109 | GRPC_ERROR_STR_DESCRIPTION, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 110 | /// source file in which this error occurred |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 111 | GRPC_ERROR_STR_FILE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 112 | /// operating system description of this error |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 113 | GRPC_ERROR_STR_OS_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 114 | /// syscall that generated this error |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 115 | GRPC_ERROR_STR_SYSCALL, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 116 | /// peer that we were trying to communicate when this error occurred |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 117 | GRPC_ERROR_STR_TARGET_ADDRESS, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 118 | /// grpc status message associated with this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 119 | GRPC_ERROR_STR_GRPC_MESSAGE, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 120 | /// hex dump (or similar) with the data that generated this error |
Craig Tiller | 781bab53 | 2016-05-05 08:15:28 -0700 | [diff] [blame] | 121 | GRPC_ERROR_STR_RAW_BYTES, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 122 | /// tsi error string associated with this error |
Craig Tiller | 804ff71 | 2016-05-05 16:25:40 -0700 | [diff] [blame] | 123 | GRPC_ERROR_STR_TSI_ERROR, |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 124 | /// filename that we were trying to read/write when this error occurred |
Craig Tiller | 4727b9b | 2016-05-17 17:19:19 -0700 | [diff] [blame] | 125 | GRPC_ERROR_STR_FILENAME, |
Craig Tiller | 936f1ea | 2016-10-14 15:15:19 -0700 | [diff] [blame] | 126 | /// which data was queued for writing when the error occurred |
Craig Tiller | 7c70b6c | 2017-01-23 07:48:42 -0800 | [diff] [blame] | 127 | GRPC_ERROR_STR_QUEUED_BUFFERS, |
| 128 | /// key associated with the error |
| 129 | GRPC_ERROR_STR_KEY, |
| 130 | /// value associated with the error |
| 131 | GRPC_ERROR_STR_VALUE, |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 132 | } grpc_error_strs; |
| 133 | |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 134 | typedef enum { |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 135 | /// timestamp of error creation |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 136 | GRPC_ERROR_TIME_CREATED, |
| 137 | } grpc_error_times; |
| 138 | |
Craig Tiller | 86037cd0 | 2016-09-02 19:58:43 -0700 | [diff] [blame] | 139 | /// The following "special" errors can be propagated without allocating memory. |
| 140 | /// They are always even so that other code (particularly combiner locks) can |
| 141 | /// safely use the lower bit for themselves. |
| 142 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 143 | #define GRPC_ERROR_NONE ((grpc_error *)NULL) |
Craig Tiller | 86037cd0 | 2016-09-02 19:58:43 -0700 | [diff] [blame] | 144 | #define GRPC_ERROR_OOM ((grpc_error *)2) |
| 145 | #define GRPC_ERROR_CANCELLED ((grpc_error *)4) |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 146 | |
| 147 | const char *grpc_error_string(grpc_error *error); |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 148 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 149 | /// Create an error - but use GRPC_ERROR_CREATE instead |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 150 | grpc_error *grpc_error_create(const char *file, int line, const char *desc, |
| 151 | grpc_error **referencing, size_t num_referencing); |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 152 | /// Create an error (this is the preferred way of generating an error that is |
| 153 | /// not due to a system call - for system calls, use GRPC_OS_ERROR or |
| 154 | /// GRPC_WSA_ERROR as appropriate) |
| 155 | /// \a referencing is an array of num_referencing elements indicating one or |
| 156 | /// more errors that are believed to have contributed to this one |
| 157 | /// err = grpc_error_create(x, y, z, r, nr) is equivalent to: |
| 158 | /// err = grpc_error_create(x, y, z, NULL, 0); |
| 159 | /// for (i=0; i<nr; i++) err = grpc_error_add_child(err, r[i]); |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 160 | #define GRPC_ERROR_CREATE(desc) \ |
| 161 | grpc_error_create(__FILE__, __LINE__, desc, NULL, 0) |
David Garcia Quintas | 32ec133 | 2016-05-11 12:22:53 -0700 | [diff] [blame] | 162 | |
| 163 | // Create an error that references some other errors. This function adds a |
| 164 | // reference to each error in errs - it does not consume an existing reference |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 165 | #define GRPC_ERROR_CREATE_REFERENCING(desc, errs, count) \ |
| 166 | grpc_error_create(__FILE__, __LINE__, desc, errs, count) |
Craig Tiller | f707d62 | 2016-05-06 14:26:12 -0700 | [diff] [blame] | 167 | |
Craig Tiller | 065b139 | 2017-01-09 14:05:07 -0800 | [diff] [blame] | 168 | //#define GRPC_ERROR_REFCOUNT_DEBUG |
Craig Tiller | e0d6c57 | 2016-05-13 07:23:36 -0700 | [diff] [blame] | 169 | #ifdef GRPC_ERROR_REFCOUNT_DEBUG |
Craig Tiller | 9ccf5f1 | 2016-05-07 21:41:01 -0700 | [diff] [blame] | 170 | grpc_error *grpc_error_ref(grpc_error *err, const char *file, int line, |
| 171 | const char *func); |
| 172 | void grpc_error_unref(grpc_error *err, const char *file, int line, |
| 173 | const char *func); |
| 174 | #define GRPC_ERROR_REF(err) grpc_error_ref(err, __FILE__, __LINE__, __func__) |
| 175 | #define GRPC_ERROR_UNREF(err) \ |
| 176 | grpc_error_unref(err, __FILE__, __LINE__, __func__) |
Craig Tiller | e0d6c57 | 2016-05-13 07:23:36 -0700 | [diff] [blame] | 177 | #else |
| 178 | grpc_error *grpc_error_ref(grpc_error *err); |
| 179 | void grpc_error_unref(grpc_error *err); |
| 180 | #define GRPC_ERROR_REF(err) grpc_error_ref(err) |
| 181 | #define GRPC_ERROR_UNREF(err) grpc_error_unref(err) |
| 182 | #endif |
Craig Tiller | f707d62 | 2016-05-06 14:26:12 -0700 | [diff] [blame] | 183 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 184 | 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] | 185 | intptr_t value) GRPC_MUST_USE_RESULT; |
Craig Tiller | 965eab3 | 2016-05-07 22:11:37 -0700 | [diff] [blame] | 186 | bool grpc_error_get_int(grpc_error *error, grpc_error_ints which, intptr_t *p); |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 187 | grpc_error *grpc_error_set_time(grpc_error *src, grpc_error_times which, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 188 | gpr_timespec value) GRPC_MUST_USE_RESULT; |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 189 | grpc_error *grpc_error_set_str(grpc_error *src, grpc_error_strs which, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 190 | const char *value) GRPC_MUST_USE_RESULT; |
Mark D. Roth | 5d11e43 | 2016-06-23 13:14:05 -0700 | [diff] [blame] | 191 | /// Returns NULL if the specified string is not set. |
| 192 | /// Caller does NOT own return value. |
| 193 | const char *grpc_error_get_str(grpc_error *error, grpc_error_strs which); |
Mark D. Roth | 1e35b69 | 2016-09-02 13:44:32 -0700 | [diff] [blame] | 194 | |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 195 | /// Add a child error: an error that is believed to have contributed to this |
| 196 | /// error occurring. Allows root causing high level errors from lower level |
| 197 | /// errors that contributed to them. |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 198 | grpc_error *grpc_error_add_child(grpc_error *src, |
| 199 | grpc_error *child) GRPC_MUST_USE_RESULT; |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 200 | grpc_error *grpc_os_error(const char *file, int line, int err, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 201 | const char *call_name) GRPC_MUST_USE_RESULT; |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 202 | /// create an error associated with errno!=0 (an 'operating system' error) |
Craig Tiller | c027e77 | 2016-05-03 16:27:00 -0700 | [diff] [blame] | 203 | #define GRPC_OS_ERROR(err, call_name) \ |
| 204 | grpc_os_error(__FILE__, __LINE__, err, call_name) |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 205 | grpc_error *grpc_wsa_error(const char *file, int line, int err, |
Craig Tiller | f0f70a8 | 2016-06-23 13:55:06 -0700 | [diff] [blame] | 206 | const char *call_name) GRPC_MUST_USE_RESULT; |
Craig Tiller | a65475c | 2016-06-02 15:57:44 -0700 | [diff] [blame] | 207 | /// windows only: create an error associated with WSAGetLastError()!=0 |
Craig Tiller | a41ac57 | 2016-05-17 16:08:17 -0700 | [diff] [blame] | 208 | #define GRPC_WSA_ERROR(err, call_name) \ |
| 209 | grpc_wsa_error(__FILE__, __LINE__, err, call_name) |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 210 | |
Craig Tiller | 4f1d0f3 | 2016-05-06 17:12:37 -0700 | [diff] [blame] | 211 | bool grpc_log_if_error(const char *what, grpc_error *error, const char *file, |
| 212 | int line); |
| 213 | #define GRPC_LOG_IF_ERROR(what, error) \ |
| 214 | grpc_log_if_error((what), (error), __FILE__, __LINE__) |
| 215 | |
Mark D. Roth | 757e84e | 2016-10-06 13:07:53 -0700 | [diff] [blame] | 216 | #ifdef __cplusplus |
| 217 | } |
| 218 | #endif |
| 219 | |
Craig Tiller | 27f59af | 2016-04-28 14:19:48 -0700 | [diff] [blame] | 220 | #endif /* GRPC_CORE_LIB_IOMGR_ERROR_H */ |