diff options
Diffstat (limited to 'src/core/lib/iomgr/error.h')
| -rw-r--r-- | src/core/lib/iomgr/error.h | 192 |
1 files changed, 192 insertions, 0 deletions
diff --git a/src/core/lib/iomgr/error.h b/src/core/lib/iomgr/error.h new file mode 100644 index 0000000000..69cdf3028e --- /dev/null +++ b/src/core/lib/iomgr/error.h @@ -0,0 +1,192 @@ +/* + * + * Copyright 2016, Google Inc. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following disclaimer + * in the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Google Inc. nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +#ifndef GRPC_CORE_LIB_IOMGR_ERROR_H +#define GRPC_CORE_LIB_IOMGR_ERROR_H + +#include <stdbool.h> +#include <stdint.h> + +#include <grpc/support/time.h> + +/// Opaque representation of an error. +/// Errors are refcounted objects that represent the result of an operation. +/// Ownership laws: +/// if a grpc_error is returned by a function, the caller owns a ref to that +/// instance +/// if a grpc_error is passed to a grpc_closure callback function (functions +/// with the signature: +/// void (*f)(grpc_exec_ctx *exec_ctx, void *arg, grpc_error *error)) +/// then those functions do not automatically own a ref to error +/// if a grpc_error is passed to *ANY OTHER FUNCTION* then that function takes +/// ownership of the error +/// Errors have: +/// a set of ints, strings, and timestamps that describe the error +/// always present are: +/// GRPC_ERROR_STR_FILE, GRPC_ERROR_INT_FILE_LINE - source location the error +/// was generated +/// GRPC_ERROR_STR_DESCRIPTION - a human readable description of the error +/// GRPC_ERROR_TIME_CREATED - a timestamp indicating when the error happened +/// an error can also have children; these are other errors that are believed +/// to have contributed to this one. By accumulating children, we can begin +/// to root cause high level failures from low level failures, without having +/// to derive execution paths from log lines +typedef struct grpc_error grpc_error; + +typedef enum { + /// 'errno' from the operating system + GRPC_ERROR_INT_ERRNO, + /// __LINE__ from the call site creating the error + GRPC_ERROR_INT_FILE_LINE, + /// stream identifier: for errors that are associated with an individual + /// wire stream + GRPC_ERROR_INT_STREAM_ID, + /// grpc status code representing this error + GRPC_ERROR_INT_GRPC_STATUS, + /// offset into some binary blob (usually represented by + /// GRPC_ERROR_STR_RAW_BYTES) where the error occurred + GRPC_ERROR_INT_OFFSET, + /// context sensitive index associated with the error + GRPC_ERROR_INT_INDEX, + /// context sensitive size associated with the error + GRPC_ERROR_INT_SIZE, + /// http2 error code associated with the error (see the HTTP2 RFC) + GRPC_ERROR_INT_HTTP2_ERROR, + /// TSI status code associated with the error + GRPC_ERROR_INT_TSI_CODE, + /// grpc_security_status associated with the error + GRPC_ERROR_INT_SECURITY_STATUS, + /// WSAGetLastError() reported when this error occurred + GRPC_ERROR_INT_WSA_ERROR, + /// File descriptor associated with this error + GRPC_ERROR_INT_FD, + /// HTTP status (i.e. 404) + GRPC_ERROR_INT_HTTP_STATUS, +} grpc_error_ints; + +typedef enum { + /// top-level textual description of this error + GRPC_ERROR_STR_DESCRIPTION, + /// source file in which this error occurred + GRPC_ERROR_STR_FILE, + /// operating system description of this error + GRPC_ERROR_STR_OS_ERROR, + /// syscall that generated this error + GRPC_ERROR_STR_SYSCALL, + /// peer that we were trying to communicate when this error occurred + GRPC_ERROR_STR_TARGET_ADDRESS, + /// grpc status message associated with this error + GRPC_ERROR_STR_GRPC_MESSAGE, + /// hex dump (or similar) with the data that generated this error + GRPC_ERROR_STR_RAW_BYTES, + /// tsi error string associated with this error + GRPC_ERROR_STR_TSI_ERROR, + /// filename that we were trying to read/write when this error occurred + GRPC_ERROR_STR_FILENAME, +} grpc_error_strs; + +typedef enum { + /// timestamp of error creation + GRPC_ERROR_TIME_CREATED, +} grpc_error_times; + +#define GRPC_ERROR_NONE ((grpc_error *)NULL) +#define GRPC_ERROR_OOM ((grpc_error *)1) +#define GRPC_ERROR_CANCELLED ((grpc_error *)2) + +const char *grpc_error_string(grpc_error *error); +void grpc_error_free_string(const char *str); + +/// Create an error - but use GRPC_ERROR_CREATE instead +grpc_error *grpc_error_create(const char *file, int line, const char *desc, + grpc_error **referencing, size_t num_referencing); +/// Create an error (this is the preferred way of generating an error that is +/// not due to a system call - for system calls, use GRPC_OS_ERROR or +/// GRPC_WSA_ERROR as appropriate) +/// \a referencing is an array of num_referencing elements indicating one or +/// more errors that are believed to have contributed to this one +/// err = grpc_error_create(x, y, z, r, nr) is equivalent to: +/// err = grpc_error_create(x, y, z, NULL, 0); +/// for (i=0; i<nr; i++) err = grpc_error_add_child(err, r[i]); +#define GRPC_ERROR_CREATE(desc) \ + grpc_error_create(__FILE__, __LINE__, desc, NULL, 0) + +// Create an error that references some other errors. This function adds a +// reference to each error in errs - it does not consume an existing reference +#define GRPC_ERROR_CREATE_REFERENCING(desc, errs, count) \ + grpc_error_create(__FILE__, __LINE__, desc, errs, count) + +//#define GRPC_ERROR_REFCOUNT_DEBUG +#ifdef GRPC_ERROR_REFCOUNT_DEBUG +grpc_error *grpc_error_ref(grpc_error *err, const char *file, int line, + const char *func); +void grpc_error_unref(grpc_error *err, const char *file, int line, + const char *func); +#define GRPC_ERROR_REF(err) grpc_error_ref(err, __FILE__, __LINE__, __func__) +#define GRPC_ERROR_UNREF(err) \ + grpc_error_unref(err, __FILE__, __LINE__, __func__) +#else +grpc_error *grpc_error_ref(grpc_error *err); +void grpc_error_unref(grpc_error *err); +#define GRPC_ERROR_REF(err) grpc_error_ref(err) +#define GRPC_ERROR_UNREF(err) grpc_error_unref(err) +#endif + +grpc_error *grpc_error_set_int(grpc_error *src, grpc_error_ints which, + intptr_t value); +bool grpc_error_get_int(grpc_error *error, grpc_error_ints which, intptr_t *p); +grpc_error *grpc_error_set_time(grpc_error *src, grpc_error_times which, + gpr_timespec value); +grpc_error *grpc_error_set_str(grpc_error *src, grpc_error_strs which, + const char *value); +/// Add a child error: an error that is believed to have contributed to this +/// error occurring. Allows root causing high level errors from lower level +/// errors that contributed to them. +grpc_error *grpc_error_add_child(grpc_error *src, grpc_error *child); +grpc_error *grpc_os_error(const char *file, int line, int err, + const char *call_name); +/// create an error associated with errno!=0 (an 'operating system' error) +#define GRPC_OS_ERROR(err, call_name) \ + grpc_os_error(__FILE__, __LINE__, err, call_name) +grpc_error *grpc_wsa_error(const char *file, int line, int err, + const char *call_name); +/// windows only: create an error associated with WSAGetLastError()!=0 +#define GRPC_WSA_ERROR(err, call_name) \ + grpc_wsa_error(__FILE__, __LINE__, err, call_name) + +bool grpc_log_if_error(const char *what, grpc_error *error, const char *file, + int line); +#define GRPC_LOG_IF_ERROR(what, error) \ + grpc_log_if_error((what), (error), __FILE__, __LINE__) + +#endif /* GRPC_CORE_LIB_IOMGR_ERROR_H */ |