/* * * 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 #include #include /// 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