GRPC C++  1.26.0
Macros | Typedefs | Enumerations | Functions | Variables
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/inlined_vector.h"

Go to the source code of this file.

Macros

#define GRPC_ERROR_NONE   ((grpc_error*)NULL)
 The following "special" errors can be propagated without allocating memory. More...
 
#define GRPC_ERROR_RESERVED_1   ((grpc_error*)1)
 
#define GRPC_ERROR_OOM   ((grpc_error*)2)
 
#define GRPC_ERROR_RESERVED_2   ((grpc_error*)3)
 
#define GRPC_ERROR_CANCELLED   ((grpc_error*)4)
 
#define GRPC_ERROR_SPECIAL_MAX   GRPC_ERROR_CANCELLED
 
#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_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_ERROR_REF(err)   grpc_error_ref(err, __FILE__, __LINE__)
 
#define GRPC_ERROR_UNREF(err)   grpc_error_unref(err, __FILE__, __LINE__)
 
#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...
 

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, GRPC_ERROR_INT_SIZE, GRPC_ERROR_INT_HTTP2_ERROR,
  GRPC_ERROR_INT_TSI_CODE, GRPC_ERROR_INT_SECURITY_STATUS, GRPC_ERROR_INT_WSA_ERROR, GRPC_ERROR_INT_FD,
  GRPC_ERROR_INT_HTTP_STATUS, GRPC_ERROR_INT_LIMIT, GRPC_ERROR_INT_OCCURRED_DURING_WRITE, GRPC_ERROR_INT_CHANNEL_CONNECTIVITY_STATE,
  GRPC_ERROR_INT_MAX
}
 
enum  grpc_error_strs {
  GRPC_ERROR_STR_DESCRIPTION, GRPC_ERROR_STR_FILE, 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_QUEUED_BUFFERS, GRPC_ERROR_STR_KEY, GRPC_ERROR_STR_VALUE,
  GRPC_ERROR_STR_MAX
}
 
enum  grpc_error_times { GRPC_ERROR_TIME_CREATED, GRPC_ERROR_TIME_MAX }
 

Functions

bool grpc_error_is_special (struct grpc_error *err)
 
void grpc_disable_error_creation ()
 
void grpc_enable_error_creation ()
 
const char * grpc_error_string (grpc_error *error)
 
grpc_errorgrpc_error_create (const char *file, int line, const grpc_slice &desc, grpc_error **referencing, size_t num_referencing)
 Create an error - but use GRPC_ERROR_CREATE instead. More...
 
grpc_errorgrpc_error_do_ref (grpc_error *err, const char *file, int line)
 
void grpc_error_do_unref (grpc_error *err, const char *file, int line)
 
grpc_errorgrpc_error_ref (grpc_error *err, const char *file, int line)
 
void grpc_error_unref (grpc_error *err, const char *file, int line)
 
grpc_errorgrpc_error_set_int (grpc_error *src, grpc_error_ints which, intptr_t value) GRPC_MUST_USE_RESULT
 
bool grpc_error_get_int (grpc_error *error, grpc_error_ints which, intptr_t *p)
 It is an error to pass nullptr as p. More...
 
grpc_errorgrpc_error_set_str (grpc_error *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 *error, grpc_error_strs which, grpc_slice *s)
 Returns false if the specified string is not set. More...
 
grpc_errorgrpc_error_add_child (grpc_error *src, grpc_error *child) GRPC_MUST_USE_RESULT
 Add a child error: an error that is believed to have contributed to this error occurring. More...
 
grpc_errorgrpc_os_error (const char *file, int line, int err, const char *call_name) GRPC_MUST_USE_RESULT
 
grpc_errorgrpc_assert_never_ok (grpc_error *error)
 
grpc_errorgrpc_wsa_error (const char *file, int line, int err, const char *call_name) GRPC_MUST_USE_RESULT
 
bool grpc_log_error (const char *what, grpc_error *error, const char *file, int line)
 
bool grpc_log_if_error (const char *what, grpc_error *error, const char *file, int line)
 

Variables

grpc_core::DebugOnlyTraceFlag grpc_trace_error_refcount
 

Macro Definition Documentation

◆ GRPC_ERROR_CANCELLED

#define GRPC_ERROR_CANCELLED   ((grpc_error*)4)

◆ GRPC_ERROR_CREATE_FROM_COPIED_STRING

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

◆ GRPC_ERROR_CREATE_FROM_STATIC_STRING

#define GRPC_ERROR_CREATE_FROM_STATIC_STRING (   desc)
Value:
NULL, 0)
grpc_error * grpc_error_create(const char *file, int line, const grpc_slice &desc, grpc_error **referencing, size_t num_referencing)
Create an error - but use GRPC_ERROR_CREATE instead.
GPRAPI grpc_slice grpc_slice_from_static_string(const char *source)
Create a slice pointing to constant memory.

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_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:
errs, count)
GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source)
Create a slice by copying a string.
grpc_error * grpc_error_create(const char *file, int line, const grpc_slice &desc, grpc_error **referencing, size_t num_referencing)
Create an error - but use GRPC_ERROR_CREATE instead.

◆ GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING

#define GRPC_ERROR_CREATE_REFERENCING_FROM_STATIC_STRING (   desc,
  errs,
  count 
)
Value:
errs, count)
grpc_error * grpc_error_create(const char *file, int line, const grpc_slice &desc, grpc_error **referencing, size_t num_referencing)
Create an error - but use GRPC_ERROR_CREATE instead.
GPRAPI grpc_slice grpc_slice_from_static_string(const char *source)
Create a slice pointing to constant memory.

◆ GRPC_ERROR_NONE

#define GRPC_ERROR_NONE   ((grpc_error*)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*)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*)1)

◆ GRPC_ERROR_RESERVED_2

#define GRPC_ERROR_RESERVED_2   ((grpc_error*)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.

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_SECURITY_STATUS 

grpc_security_status 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_LIMIT 

context sensitive limit associated with the error

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_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_QUEUED_BUFFERS 

which data was queued for writing when the 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* grpc_assert_never_ok ( grpc_error 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* grpc_error_add_child ( grpc_error src,
grpc_error 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* grpc_error_create ( const char *  file,
int  line,
const grpc_slice desc,
grpc_error **  referencing,
size_t  num_referencing 
)

Create an error - but use GRPC_ERROR_CREATE instead.

◆ grpc_error_do_ref()

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

◆ grpc_error_do_unref()

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

◆ grpc_error_get_int()

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

It is an error to pass nullptr as p.

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

◆ grpc_error_get_str()

bool grpc_error_get_str ( grpc_error 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 ( struct grpc_error err)
inline

◆ grpc_error_ref()

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

◆ grpc_error_set_int()

grpc_error* grpc_error_set_int ( grpc_error src,
grpc_error_ints  which,
intptr_t  value 
)

◆ grpc_error_set_str()

grpc_error* grpc_error_set_str ( grpc_error 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_string()

const char* grpc_error_string ( grpc_error error)

◆ grpc_error_unref()

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

◆ grpc_log_error()

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

◆ grpc_log_if_error()

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

◆ grpc_os_error()

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

◆ grpc_wsa_error()

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

Variable Documentation

◆ grpc_trace_error_refcount

grpc_core::DebugOnlyTraceFlag grpc_trace_error_refcount