GRPC Core  18.0.0
Macros | Typedefs | Enumerations | Functions
error.h File Reference
#include <grpc/support/port_platform.h>
#include <inttypes.h>
#include <stdbool.h>
#include <grpc/slice.h>
#include <grpc/status.h>
#include <grpc/support/log.h>
#include <grpc/support/time.h>
#include "src/core/lib/debug/trace.h"
#include "src/core/lib/gprpp/status_helper.h"
#include "absl/status/status.h"

Go to the source code of this file.

Macros

#define GRPC_ERROR_NONE   ((grpc_error_handle)NULL)
 The following "special" errors can be propagated without allocating memory. More...
 
#define GRPC_ERROR_RESERVED_1   ((grpc_error_handle)1)
 
#define GRPC_ERROR_OOM   ((grpc_error_handle)2)
 
#define GRPC_ERROR_RESERVED_2   ((grpc_error_handle)3)
 
#define GRPC_ERROR_CANCELLED   ((grpc_error_handle)4)
 
#define GRPC_ERROR_SPECIAL_MAX   GRPC_ERROR_CANCELLED
 
#define GRPC_ERROR_REF(err)   grpc_error_ref(err, __FILE__, __LINE__)
 
#define GRPC_ERROR_UNREF(err)   grpc_error_unref(err, __FILE__, __LINE__)
 
#define GRPC_ERROR_CREATE_FROM_STATIC_STRING(desc)
 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) 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]);. More...
 
#define GRPC_ERROR_CREATE_FROM_COPIED_STRING(desc)
 
#define GRPC_ERROR_CREATE_FROM_STRING_VIEW(desc)
 
#define GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING(desc, errs, count)
 
#define GRPC_ERROR_CREATE_REFERENCING_FROM_COPIED_STRING(desc, errs, count)
 
#define GRPC_ERROR_CREATE_FROM_VECTOR(desc, error_list)    grpc_error_create_from_vector(__FILE__, __LINE__, desc, error_list)
 
#define GRPC_OS_ERROR(err, call_name)    grpc_assert_never_ok(grpc_os_error(__FILE__, __LINE__, err, call_name))
 create an error associated with errno!=0 (an 'operating system' error) More...
 
#define GRPC_WSA_ERROR(err, call_name)    grpc_wsa_error(__FILE__, __LINE__, err, call_name)
 windows only: create an error associated with WSAGetLastError()!=0 More...
 
#define GRPC_LOG_IF_ERROR(what, error)    (grpc_log_if_error((what), (error), __FILE__, __LINE__))
 

Typedefs

typedef struct grpc_error grpc_error
 Opaque representation of an error. More...
 
typedef grpc_errorgrpc_error_handle
 

Enumerations

enum  grpc_error_ints {
  GRPC_ERROR_INT_ERRNO , GRPC_ERROR_INT_FILE_LINE , GRPC_ERROR_INT_STREAM_ID , GRPC_ERROR_INT_GRPC_STATUS ,
  GRPC_ERROR_INT_OFFSET , GRPC_ERROR_INT_INDEX = static_cast<int>(grpc_core::StatusIntProperty::kIndex) , GRPC_ERROR_INT_SIZE = static_cast<int>(grpc_core::StatusIntProperty::kSize) , GRPC_ERROR_INT_HTTP2_ERROR ,
  GRPC_ERROR_INT_TSI_CODE , GRPC_ERROR_INT_WSA_ERROR , GRPC_ERROR_INT_FD = static_cast<int>(grpc_core::StatusIntProperty::kFd) , GRPC_ERROR_INT_HTTP_STATUS ,
  GRPC_ERROR_INT_OCCURRED_DURING_WRITE , GRPC_ERROR_INT_CHANNEL_CONNECTIVITY_STATE , GRPC_ERROR_INT_LB_POLICY_DROP , GRPC_ERROR_INT_MAX
}
 
enum  grpc_error_strs {
  GRPC_ERROR_STR_DESCRIPTION , GRPC_ERROR_STR_FILE = static_cast<int>(grpc_core::StatusStrProperty::kFile) , GRPC_ERROR_STR_OS_ERROR , GRPC_ERROR_STR_SYSCALL ,
  GRPC_ERROR_STR_TARGET_ADDRESS , GRPC_ERROR_STR_GRPC_MESSAGE , GRPC_ERROR_STR_RAW_BYTES , GRPC_ERROR_STR_TSI_ERROR ,
  GRPC_ERROR_STR_FILENAME , GRPC_ERROR_STR_KEY = static_cast<int>(grpc_core::StatusStrProperty::kKey) , GRPC_ERROR_STR_VALUE = static_cast<int>(grpc_core::StatusStrProperty::kValue) , GRPC_ERROR_STR_MAX
}
 
enum  grpc_error_times { GRPC_ERROR_TIME_CREATED , GRPC_ERROR_TIME_MAX }
 

Functions

const char * grpc_error_string (grpc_error_handle error)
 
std::string grpc_error_std_string (grpc_error_handle error)
 
void grpc_disable_error_creation ()
 
void grpc_enable_error_creation ()
 
bool grpc_error_is_special (grpc_error_handle err)
 
grpc_error_handle grpc_error_do_ref (grpc_error_handle err, const char *file, int line)
 
void grpc_error_do_unref (grpc_error_handle err, const char *file, int line)
 
grpc_error_handle grpc_error_ref (grpc_error_handle err, const char *file, int line)
 
void grpc_error_unref (grpc_error_handle err, const char *file, int line)
 
grpc_error_handle grpc_error_create (const char *file, int line, const grpc_slice &desc, grpc_error_handle *referencing, size_t num_referencing)
 Create an error - but use GRPC_ERROR_CREATE instead. More...
 
grpc_error_handle grpc_os_error (const char *file, int line, int err, const char *call_name) GRPC_MUST_USE_RESULT
 
grpc_error_handle grpc_assert_never_ok (grpc_error_handle error)
 
grpc_error_handle grpc_wsa_error (const char *file, int line, int err, const char *call_name) GRPC_MUST_USE_RESULT
 
grpc_error_handle grpc_error_set_int (grpc_error_handle src, grpc_error_ints which, intptr_t value) GRPC_MUST_USE_RESULT
 
bool grpc_error_get_int (grpc_error_handle error, grpc_error_ints which, intptr_t *p)
 It is an error to pass nullptr as p. More...
 
grpc_error_handle grpc_error_set_str (grpc_error_handle src, grpc_error_strs which, const grpc_slice &str) GRPC_MUST_USE_RESULT
 This call takes ownership of the slice; the error is responsible for eventually unref-ing it. More...
 
bool grpc_error_get_str (grpc_error_handle error, grpc_error_strs which, grpc_slice *s)
 Returns false if the specified string is not set. More...
 
grpc_error_handle grpc_error_add_child (grpc_error_handle src, grpc_error_handle child) GRPC_MUST_USE_RESULT
 Add a child error: an error that is believed to have contributed to this error occurring. More...
 
bool grpc_log_error (const char *what, grpc_error_handle error, const char *file, int line)
 
bool grpc_log_if_error (const char *what, grpc_error_handle error, const char *file, int line)
 

Macro Definition Documentation

◆ GRPC_ERROR_CANCELLED

#define GRPC_ERROR_CANCELLED   ((grpc_error_handle)4)

◆ GRPC_ERROR_CREATE_FROM_COPIED_STRING

#define GRPC_ERROR_CREATE_FROM_COPIED_STRING (   desc)
Value:
grpc_error_create(__FILE__, __LINE__, grpc_slice_from_copied_string(desc), \
NULL, 0)
grpc_error_handle grpc_error_create(const char *file, int line, const grpc_slice &desc, grpc_error_handle *referencing, size_t num_referencing)
Create an error - but use GRPC_ERROR_CREATE instead.
Definition: error.cc:416
GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source)
Create a slice by copying a string.
Definition: slice.cc:229

◆ GRPC_ERROR_CREATE_FROM_STATIC_STRING

#define GRPC_ERROR_CREATE_FROM_STATIC_STRING (   desc)
Value:
grpc_error_create(__FILE__, __LINE__, grpc_slice_from_static_string(desc), \
NULL, 0)
GPRAPI grpc_slice grpc_slice_from_static_string(const char *source)
Create a slice pointing to constant memory.
Definition: slice.cc:108

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) 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]);.

◆ GRPC_ERROR_CREATE_FROM_STRING_VIEW

#define GRPC_ERROR_CREATE_FROM_STRING_VIEW (   desc)
Value:
__FILE__, __LINE__, \
grpc_slice_from_copied_buffer((desc).data(), (desc).size()), NULL, 0)
GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char *source, size_t len)
Create a slice by copying a buffer.
Definition: slice.cc:225

◆ GRPC_ERROR_CREATE_FROM_VECTOR

#define GRPC_ERROR_CREATE_FROM_VECTOR (   desc,
  error_list 
)     grpc_error_create_from_vector(__FILE__, __LINE__, desc, error_list)

◆ GRPC_ERROR_CREATE_REFERENCING_FROM_COPIED_STRING

#define GRPC_ERROR_CREATE_REFERENCING_FROM_COPIED_STRING (   desc,
  errs,
  count 
)
Value:
grpc_error_create(__FILE__, __LINE__, grpc_slice_from_copied_string(desc), \
errs, count)

◆ GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING

#define GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING (   desc,
  errs,
  count 
)
Value:
grpc_error_create(__FILE__, __LINE__, grpc_slice_from_static_string(desc), \
errs, count)

◆ GRPC_ERROR_NONE

#define GRPC_ERROR_NONE   ((grpc_error_handle)NULL)

The following "special" errors can be propagated without allocating memory.

They are always even so that other code (particularly combiner locks, polling engines) can safely use the lower bit for themselves.

◆ GRPC_ERROR_OOM

#define GRPC_ERROR_OOM   ((grpc_error_handle)2)

◆ GRPC_ERROR_REF

#define GRPC_ERROR_REF (   err)    grpc_error_ref(err, __FILE__, __LINE__)

◆ GRPC_ERROR_RESERVED_1

#define GRPC_ERROR_RESERVED_1   ((grpc_error_handle)1)

◆ GRPC_ERROR_RESERVED_2

#define GRPC_ERROR_RESERVED_2   ((grpc_error_handle)3)

◆ GRPC_ERROR_SPECIAL_MAX

#define GRPC_ERROR_SPECIAL_MAX   GRPC_ERROR_CANCELLED

◆ GRPC_ERROR_UNREF

#define GRPC_ERROR_UNREF (   err)    grpc_error_unref(err, __FILE__, __LINE__)

◆ GRPC_LOG_IF_ERROR

#define GRPC_LOG_IF_ERROR (   what,
  error 
)     (grpc_log_if_error((what), (error), __FILE__, __LINE__))

◆ GRPC_OS_ERROR

#define GRPC_OS_ERROR (   err,
  call_name 
)     grpc_assert_never_ok(grpc_os_error(__FILE__, __LINE__, err, call_name))

create an error associated with errno!=0 (an 'operating system' error)

◆ GRPC_WSA_ERROR

#define GRPC_WSA_ERROR (   err,
  call_name 
)     grpc_wsa_error(__FILE__, __LINE__, err, call_name)

windows only: create an error associated with WSAGetLastError()!=0

Typedef Documentation

◆ grpc_error

typedef struct grpc_error grpc_error

Opaque representation of an error.

See https://github.com/grpc/grpc/blob/master/doc/core/grpc-error.md for a full write up of this object.

◆ grpc_error_handle

Enumeration Type Documentation

◆ grpc_error_ints

Enumerator
GRPC_ERROR_INT_ERRNO 

'errno' from the operating system

GRPC_ERROR_INT_FILE_LINE 

LINE from the call site creating the error

GRPC_ERROR_INT_STREAM_ID 

stream identifier: for errors that are associated with an individual wire stream

GRPC_ERROR_INT_GRPC_STATUS 

grpc status code representing this error

GRPC_ERROR_INT_OFFSET 

offset into some binary blob (usually represented by GRPC_ERROR_STR_RAW_BYTES) where the error occurred

GRPC_ERROR_INT_INDEX 

context sensitive index associated with the error

GRPC_ERROR_INT_SIZE 

context sensitive size associated with the error

GRPC_ERROR_INT_HTTP2_ERROR 

http2 error code associated with the error (see the HTTP2 RFC)

GRPC_ERROR_INT_TSI_CODE 

TSI status code associated with the error.

GRPC_ERROR_INT_WSA_ERROR 

WSAGetLastError() reported when this error occurred.

GRPC_ERROR_INT_FD 

File descriptor associated with this error.

GRPC_ERROR_INT_HTTP_STATUS 

HTTP status (i.e. 404)

GRPC_ERROR_INT_OCCURRED_DURING_WRITE 

chttp2: did the error occur while a write was in progress

GRPC_ERROR_INT_CHANNEL_CONNECTIVITY_STATE 

channel connectivity state associated with the error

GRPC_ERROR_INT_LB_POLICY_DROP 

LB policy drop.

GRPC_ERROR_INT_MAX 

Must always be last.

◆ grpc_error_strs

Enumerator
GRPC_ERROR_STR_DESCRIPTION 

top-level textual description of this error

GRPC_ERROR_STR_FILE 

source file in which this error occurred

GRPC_ERROR_STR_OS_ERROR 

operating system description of this error

GRPC_ERROR_STR_SYSCALL 

syscall that generated this error

GRPC_ERROR_STR_TARGET_ADDRESS 

peer that we were trying to communicate when this error occurred

GRPC_ERROR_STR_GRPC_MESSAGE 

grpc status message associated with this error

GRPC_ERROR_STR_RAW_BYTES 

hex dump (or similar) with the data that generated this error

GRPC_ERROR_STR_TSI_ERROR 

tsi error string associated with this error

GRPC_ERROR_STR_FILENAME 

filename that we were trying to read/write when this error occurred

GRPC_ERROR_STR_KEY 

key associated with the error

GRPC_ERROR_STR_VALUE 

value associated with the error

GRPC_ERROR_STR_MAX 

Must always be last.

◆ grpc_error_times

Enumerator
GRPC_ERROR_TIME_CREATED 

timestamp of error creation

GRPC_ERROR_TIME_MAX 

Must always be last.

Function Documentation

◆ grpc_assert_never_ok()

grpc_error_handle grpc_assert_never_ok ( grpc_error_handle  error)
inline

◆ grpc_disable_error_creation()

void grpc_disable_error_creation ( )

◆ grpc_enable_error_creation()

void grpc_enable_error_creation ( )

◆ grpc_error_add_child()

grpc_error_handle grpc_error_add_child ( grpc_error_handle  src,
grpc_error_handle  child 
)

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. The src error takes ownership of the child error.

Edge Conditions - 1) If either of src or child is GRPC_ERROR_NONE, returns a reference to the other argument. 2) If both src and child are GRPC_ERROR_NONE, returns GRPC_ERROR_NONE. 3) If src and child point to the same error, returns a single reference. (Note that, 2 references should have been received to the error in this case.)

◆ grpc_error_create()

grpc_error_handle grpc_error_create ( const char *  file,
int  line,
const grpc_slice desc,
grpc_error_handle referencing,
size_t  num_referencing 
)

Create an error - but use GRPC_ERROR_CREATE instead.

◆ grpc_error_do_ref()

grpc_error_handle grpc_error_do_ref ( grpc_error_handle  err,
const char *  file,
int  line 
)

◆ grpc_error_do_unref()

void grpc_error_do_unref ( grpc_error_handle  err,
const char *  file,
int  line 
)

◆ grpc_error_get_int()

bool grpc_error_get_int ( grpc_error_handle  error,
grpc_error_ints  which,
intptr_t *  p 
)

It is an error to pass nullptr as p.

Caller should allocate a phony intptr_t for p, even if the value of p is not used.

◆ grpc_error_get_str()

bool grpc_error_get_str ( grpc_error_handle  error,
grpc_error_strs  which,
grpc_slice s 
)

Returns false if the specified string is not set.

Caller does NOT own the slice.

◆ grpc_error_is_special()

bool grpc_error_is_special ( grpc_error_handle  err)
inline

◆ grpc_error_ref()

grpc_error_handle grpc_error_ref ( grpc_error_handle  err,
const char *  file,
int  line 
)
inline

◆ grpc_error_set_int()

grpc_error_handle grpc_error_set_int ( grpc_error_handle  src,
grpc_error_ints  which,
intptr_t  value 
)

◆ grpc_error_set_str()

grpc_error_handle grpc_error_set_str ( grpc_error_handle  src,
grpc_error_strs  which,
const grpc_slice str 
)

This call takes ownership of the slice; the error is responsible for eventually unref-ing it.

◆ grpc_error_std_string()

std::string grpc_error_std_string ( grpc_error_handle  error)

◆ grpc_error_string()

const char* grpc_error_string ( grpc_error_handle  error)

◆ grpc_error_unref()

void grpc_error_unref ( grpc_error_handle  err,
const char *  file,
int  line 
)
inline

◆ grpc_log_error()

bool grpc_log_error ( const char *  what,
grpc_error_handle  error,
const char *  file,
int  line 
)

◆ grpc_log_if_error()

bool grpc_log_if_error ( const char *  what,
grpc_error_handle  error,
const char *  file,
int  line 
)
inline

◆ grpc_os_error()

grpc_error_handle grpc_os_error ( const char *  file,
int  line,
int  err,
const char *  call_name 
)

◆ grpc_wsa_error()

grpc_error_handle grpc_wsa_error ( const char *  file,
int  line,
int  err,
const char *  call_name 
)