grpc 1.3.4 → 1.4.0

data/include/grpc/impl/codegen/port_platform.h

@@ -290,6 +290,12 @@
 #endif
 #endif /* GPR_NO_AUTODETECT_PLATFORM */
 
+#if defined(__has_include)
+#if __has_include(<atomic>)
+#define GRPC_HAS_CXX11_ATOMIC
+#endif /* __has_include(<atomic>) */
+#endif /* defined(__has_include) */
+
 #ifndef GPR_PLATFORM_STRING
 #warning "GPR_PLATFORM_STRING not auto-detected"
 #define GPR_PLATFORM_STRING "unknown"

data/include/grpc/impl/codegen/propagation_bits.h

@@ -40,7 +40,7 @@
 extern "C" {
 #endif
 
-/* Propagation bits: this can be bitwise or-ed to form propagation_mask for
+/** Propagation bits: this can be bitwise or-ed to form propagation_mask for
  * grpc_call */
 /** Propagate deadline */
 #define GRPC_PROPAGATE_DEADLINE ((uint32_t)1)
@@ -50,7 +50,7 @@ extern "C" {
 /** Propagate cancellation */
 #define GRPC_PROPAGATE_CANCELLATION ((uint32_t)8)
 
-/* Default propagation mask: clients of the core API are encouraged to encode
+/** Default propagation mask: clients of the core API are encouraged to encode
    deltas from this in their implementations... ie write:
    GRPC_PROPAGATE_DEFAULTS & ~GRPC_PROPAGATE_DEADLINE to disable deadline
    propagation. Doing so gives flexibility in the future to define new

data/include/grpc/impl/codegen/slice.h

@@ -34,15 +34,16 @@
 #ifndef GRPC_IMPL_CODEGEN_SLICE_H
 #define GRPC_IMPL_CODEGEN_SLICE_H
 
+#include <grpc/impl/codegen/port_platform.h>
+
 #include <stddef.h>
-#include <stdint.h>
 
 #include <grpc/impl/codegen/exec_ctx_fwd.h>
 #include <grpc/impl/codegen/gpr_slice.h>
 
 typedef struct grpc_slice grpc_slice;
 
-/* Slice API
+/** Slice API
 
    A slice represents a contiguous reference counted array of bytes.
    It is cheap to take references to a slice, and it is cheap to create a
@@ -62,14 +63,14 @@ typedef struct grpc_slice_refcount_vtable {
   uint32_t (*hash)(grpc_slice slice);
 } grpc_slice_refcount_vtable;
 
-/* Reference count container for grpc_slice. Contains function pointers to
+/** Reference count container for grpc_slice. Contains function pointers to
    increment and decrement reference counts. Implementations should cleanup
    when the reference count drops to zero.
    Typically client code should not touch this, and use grpc_slice_malloc,
    grpc_slice_new, or grpc_slice_new_with_len instead. */
 typedef struct grpc_slice_refcount {
   const grpc_slice_refcount_vtable *vtable;
-  /* If a subset of this slice is taken, use this pointer for the refcount.
+  /** If a subset of this slice is taken, use this pointer for the refcount.
      Typically points back to the refcount itself, however iterning
      implementations can use this to avoid a verification step on each hash
      or equality check */
@@ -78,7 +79,7 @@ typedef struct grpc_slice_refcount {
 
 #define GRPC_SLICE_INLINED_SIZE (sizeof(size_t) + sizeof(uint8_t *) - 1)
 
-/* A grpc_slice s, if initialized, represents the byte range
+/** A grpc_slice s, if initialized, represents the byte range
    s.bytes[0..s.length-1].
 
    It can have an associated ref count which has a destruction routine to be run
@@ -103,23 +104,23 @@ struct grpc_slice {
 
 #define GRPC_SLICE_BUFFER_INLINE_ELEMENTS 8
 
-/* Represents an expandable array of slices, to be interpreted as a
+/** Represents an expandable array of slices, to be interpreted as a
    single item. */
 typedef struct {
-  /* This is for internal use only. External users (i.e any code outside grpc
+  /** This is for internal use only. External users (i.e any code outside grpc
    * core) MUST NOT use this field */
   grpc_slice *base_slices;
 
-  /* slices in the array (Points to the first valid grpc_slice in the array) */
+  /** slices in the array (Points to the first valid grpc_slice in the array) */
   grpc_slice *slices;
-  /* the number of slices in the array */
+  /** the number of slices in the array */
   size_t count;
-  /* the number of slices allocated in the array. External users (i.e any code
+  /** the number of slices allocated in the array. External users (i.e any code
    * outside grpc core) MUST NOT use this field */
   size_t capacity;
-  /* the combined length of all slices in the array */
+  /** the combined length of all slices in the array */
   size_t length;
-  /* inlined elements to avoid allocations */
+  /** inlined elements to avoid allocations */
   grpc_slice inlined[GRPC_SLICE_BUFFER_INLINE_ELEMENTS];
 } grpc_slice_buffer;
 

data/include/grpc/impl/codegen/status.h

@@ -39,40 +39,40 @@ extern "C" {
 #endif
 
 typedef enum {
-  /* Not an error; returned on success */
+  /** Not an error; returned on success */
   GRPC_STATUS_OK = 0,
 
-  /* The operation was cancelled (typically by the caller). */
+  /** The operation was cancelled (typically by the caller). */
   GRPC_STATUS_CANCELLED = 1,
 
-  /* Unknown error.  An example of where this error may be returned is
+  /** Unknown error.  An example of where this error may be returned is
      if a Status value received from another address space belongs to
      an error-space that is not known in this address space.  Also
      errors raised by APIs that do not return enough error information
      may be converted to this error. */
   GRPC_STATUS_UNKNOWN = 2,
 
-  /* Client specified an invalid argument.  Note that this differs
+  /** Client specified an invalid argument.  Note that this differs
      from FAILED_PRECONDITION.  INVALID_ARGUMENT indicates arguments
      that are problematic regardless of the state of the system
      (e.g., a malformed file name). */
   GRPC_STATUS_INVALID_ARGUMENT = 3,
 
-  /* Deadline expired before operation could complete.  For operations
+  /** Deadline expired before operation could complete.  For operations
      that change the state of the system, this error may be returned
      even if the operation has completed successfully.  For example, a
      successful response from a server could have been delayed long
      enough for the deadline to expire. */
   GRPC_STATUS_DEADLINE_EXCEEDED = 4,
 
-  /* Some requested entity (e.g., file or directory) was not found. */
+  /** Some requested entity (e.g., file or directory) was not found. */
   GRPC_STATUS_NOT_FOUND = 5,
 
-  /* Some entity that we attempted to create (e.g., file or directory)
+  /** Some entity that we attempted to create (e.g., file or directory)
      already exists. */
   GRPC_STATUS_ALREADY_EXISTS = 6,
 
-  /* The caller does not have permission to execute the specified
+  /** The caller does not have permission to execute the specified
      operation.  PERMISSION_DENIED must not be used for rejections
      caused by exhausting some resource (use RESOURCE_EXHAUSTED
      instead for those errors).  PERMISSION_DENIED must not be
@@ -80,15 +80,15 @@ typedef enum {
      instead for those errors). */
   GRPC_STATUS_PERMISSION_DENIED = 7,
 
-  /* The request does not have valid authentication credentials for the
+  /** The request does not have valid authentication credentials for the
      operation. */
   GRPC_STATUS_UNAUTHENTICATED = 16,
 
-  /* Some resource has been exhausted, perhaps a per-user quota, or
+  /** Some resource has been exhausted, perhaps a per-user quota, or
      perhaps the entire file system is out of space. */
   GRPC_STATUS_RESOURCE_EXHAUSTED = 8,
 
-  /* Operation was rejected because the system is not in a state
+  /** Operation was rejected because the system is not in a state
      required for the operation's execution.  For example, directory
      to be deleted may be non-empty, an rmdir operation is applied to
      a non-directory, etc.
@@ -109,14 +109,14 @@ typedef enum {
           read-modify-write on the same resource. */
   GRPC_STATUS_FAILED_PRECONDITION = 9,
 
-  /* The operation was aborted, typically due to a concurrency issue
+  /** The operation was aborted, typically due to a concurrency issue
      like sequencer check failures, transaction aborts, etc.
 
      See litmus test above for deciding between FAILED_PRECONDITION,
      ABORTED, and UNAVAILABLE. */
   GRPC_STATUS_ABORTED = 10,
 
-  /* Operation was attempted past the valid range.  E.g., seeking or
+  /** Operation was attempted past the valid range.  E.g., seeking or
      reading past end of file.
 
      Unlike INVALID_ARGUMENT, this error indicates a problem that may
@@ -133,26 +133,31 @@ typedef enum {
      they are done. */
   GRPC_STATUS_OUT_OF_RANGE = 11,
 
-  /* Operation is not implemented or not supported/enabled in this service. */
+  /** Operation is not implemented or not supported/enabled in this service. */
   GRPC_STATUS_UNIMPLEMENTED = 12,
 
-  /* Internal errors.  Means some invariants expected by underlying
+  /** Internal errors.  Means some invariants expected by underlying
      system has been broken.  If you see one of these errors,
      something is very broken. */
   GRPC_STATUS_INTERNAL = 13,
 
-  /* The service is currently unavailable.  This is a most likely a
+  /** The service is currently unavailable.  This is a most likely a
      transient condition and may be corrected by retrying with
      a backoff.
 
+     WARNING: Although data MIGHT not have been transmitted when this
+     status occurs, there is NOT A GUARANTEE that the server has not seen
+     anything. So in general it is unsafe to retry on this status code
+     if the call is non-idempotent.
+
      See litmus test above for deciding between FAILED_PRECONDITION,
      ABORTED, and UNAVAILABLE. */
   GRPC_STATUS_UNAVAILABLE = 14,
 
-  /* Unrecoverable data loss or corruption. */
+  /** Unrecoverable data loss or corruption. */
   GRPC_STATUS_DATA_LOSS = 15,
 
-  /* Force users to include a default branch: */
+  /** Force users to include a default branch: */
   GRPC_STATUS__DO_NOT_USE = -1
 } grpc_status_code;
 

data/include/grpc/impl/codegen/sync.h

@@ -33,7 +33,7 @@
 
 #ifndef GRPC_IMPL_CODEGEN_SYNC_H
 #define GRPC_IMPL_CODEGEN_SYNC_H
-/* Synchronization primitives for GPR.
+/** Synchronization primitives for GPR.
 
    The type  gpr_mu              provides a non-reentrant mutex (lock).
 

data/include/grpc/load_reporting.h

@@ -35,7 +35,6 @@
 #define GRPC_LOAD_REPORTING_H
 
 #include <grpc/impl/codegen/port_platform.h>
-#include <grpc/slice.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -50,11 +49,12 @@ extern "C" {
  * gRPC LB system. */
 #define GRPC_LB_TOKEN_MD_KEY "lb-token"
 
-/** A sequence of values for load reporting purposes */
-typedef struct grpc_load_reporting_cost_context {
-  grpc_slice *values;
-  size_t values_count;
-} grpc_load_reporting_cost_context;
+/** Metadata key for gRPC LB cost reporting.
+ *
+ * The value corresponding to this key is an opaque binary blob reported by the
+ * backend as part of its trailing metadata containing cost information for the
+ * call. */
+#define GRPC_LB_COST_MD_KEY "lb-cost-bin"
 
 #ifdef __cplusplus
 }

data/include/grpc/slice.h

@@ -41,11 +41,11 @@
 extern "C" {
 #endif
 
-/* Increment the refcount of s. Requires slice is initialized.
+/** Increment the refcount of s. Requires slice is initialized.
    Returns s. */
 GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
 
-/* Decrement the ref count of s.  If the ref count of s reaches zero, all
+/** Decrement the ref count of s.  If the ref count of s reaches zero, all
    slices sharing the ref count are destroyed, and considered no longer
    initialized.  If s is ultimately derived from a call to grpc_slice_new(start,
    len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is
@@ -53,12 +53,15 @@ GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
    where dest!=NULL , then (*dest)(start, len).  Requires s initialized.  */
 GPRAPI void grpc_slice_unref(grpc_slice s);
 
-/* Create a slice pointing at some data. Calls malloc to allocate a refcount
+/** Copy slice - create a new slice that contains the same data as s */
+GPRAPI grpc_slice grpc_slice_copy(grpc_slice s);
+
+/** Create a slice pointing at some data. Calls malloc to allocate a refcount
    for the object, and arranges that destroy will be called with the pointer
    passed in at destruction. */
 GPRAPI grpc_slice grpc_slice_new(void *p, size_t len, void (*destroy)(void *));
 
-/* Equivalent to grpc_slice_new, but with a separate pointer that is
+/** Equivalent to grpc_slice_new, but with a separate pointer that is
    passed to the destroy function.  This function can be useful when
    the data is part of a larger structure that must be destroyed when
    the data is no longer needed. */
@@ -66,23 +69,30 @@ GPRAPI grpc_slice grpc_slice_new_with_user_data(void *p, size_t len,
                                                 void (*destroy)(void *),
                                                 void *user_data);
 
-/* Equivalent to grpc_slice_new, but with a two argument destroy function that
+/** Equivalent to grpc_slice_new, but with a two argument destroy function that
    also takes the slice length. */
 GPRAPI grpc_slice grpc_slice_new_with_len(void *p, size_t len,
                                           void (*destroy)(void *, size_t));
 
-/* Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
+/** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
    call.
    Aborts if malloc() fails. */
 GPRAPI grpc_slice grpc_slice_malloc(size_t length);
+GPRAPI grpc_slice grpc_slice_malloc_large(size_t length);
+
+#define GRPC_SLICE_MALLOC(len)                                    \
+  ((len) <= GRPC_SLICE_INLINED_SIZE                               \
+       ? (grpc_slice){.refcount = NULL,                           \
+                      .data.inlined = {.length = (uint8_t)(len)}} \
+       : grpc_slice_malloc_large((len)))
 
-/* Intern a slice:
+/** Intern a slice:
 
    The return value for two invocations of this function with  the same sequence
    of bytes is a slice which points to the same memory. */
 GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
 
-/* Create a slice by copying a string.
+/** Create a slice by copying a string.
    Does not preserve null terminators.
    Equivalent to:
      size_t len = strlen(source);
@@ -90,34 +100,46 @@ GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
      memcpy(slice->data, source, len); */
 GPRAPI grpc_slice grpc_slice_from_copied_string(const char *source);
 
-/* Create a slice by copying a buffer.
+/** Create a slice by copying a buffer.
    Equivalent to:
      grpc_slice slice = grpc_slice_malloc(len);
      memcpy(slice->data, source, len); */
 GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char *source, size_t len);
 
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
 GPRAPI grpc_slice grpc_slice_from_static_string(const char *source);
 
-/* Create a slice pointing to constant memory */
+/** Create a slice pointing to constant memory */
 GPRAPI grpc_slice grpc_slice_from_static_buffer(const void *source, size_t len);
 
-/* Return a result slice derived from s, which shares a ref count with s, where
-   result.data==s.data+begin, and result.length==end-begin.
-   The ref count of s is increased by one.
+/** Return a result slice derived from s, which shares a ref count with \a s,
+   where result.data==s.data+begin, and result.length==end-begin. The ref count
+   of \a s is increased by one. Do not assign result back to \a s.
    Requires s initialized, begin <= end, begin <= s.length, and
    end <= source->length. */
 GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end);
 
-/* The same as grpc_slice_sub, but without altering the ref count */
+/** The same as grpc_slice_sub, but without altering the ref count */
 GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end);
 
-/* Splits s into two: modifies s to be s[0:split], and returns a new slice,
+/** Splits s into two: modifies s to be s[0:split], and returns a new slice,
    sharing a refcount with s, that contains s[split:s.length].
    Requires s intialized, split <= s.length */
 GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice *s, size_t split);
 
-/* Splits s into two: modifies s to be s[split:s.length], and returns a new
+typedef enum {
+  GRPC_SLICE_REF_TAIL = 1,
+  GRPC_SLICE_REF_HEAD = 2,
+  GRPC_SLICE_REF_BOTH = 1 + 2
+} grpc_slice_ref_whom;
+
+/** The same as grpc_slice_split_tail, but with an option to skip altering
+ * refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to
+ * grpc_slice_split_tail(...)) */
+GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice *s, size_t split,
+                                                  grpc_slice_ref_whom ref_whom);
+
+/** Splits s into two: modifies s to be s[split:s.length], and returns a new
    slice, sharing a refcount with s, that contains s[0:split].
    Requires s intialized, split <= s.length */
 GPRAPI grpc_slice grpc_slice_split_head(grpc_slice *s, size_t split);
@@ -129,35 +151,35 @@ GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b);
 
 GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b);
 
-/* Returns <0 if a < b, ==0 if a == b, >0 if a > b
+/** Returns <0 if a < b, ==0 if a == b, >0 if a > b
    The order is arbitrary, and is not guaranteed to be stable across different
    versions of the API. */
 GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b);
 GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char *b);
 GPRAPI int grpc_slice_buf_cmp(grpc_slice a, const void *b, size_t blen);
 
-/* return non-zero if the first blen bytes of a are equal to b */
+/** return non-zero if the first blen bytes of a are equal to b */
 GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void *b, size_t blen);
 
-/* return the index of the last instance of \a c in \a s, or -1 if not found */
+/** return the index of the last instance of \a c in \a s, or -1 if not found */
 GPRAPI int grpc_slice_rchr(grpc_slice s, char c);
 GPRAPI int grpc_slice_chr(grpc_slice s, char c);
 
-/* return the index of the first occurance of \a needle in \a haystack, or -1 if
- * it's not found */
+/** return the index of the first occurance of \a needle in \a haystack, or -1
+   if it's not found */
 GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle);
 
 GPRAPI uint32_t grpc_slice_hash(grpc_slice s);
 
-/* Do two slices point at the same memory, with the same length
+/** Do two slices point at the same memory, with the same length
    If a or b is inlined, actually compares data */
 GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b);
 
-/* Return a slice pointing to newly allocated memory that has the same contents
+/** Return a slice pointing to newly allocated memory that has the same contents
  * as \a s */
 GPRAPI grpc_slice grpc_slice_dup(grpc_slice a);
 
-/* Return a copy of slice as a C string. Offers no protection against embedded
+/** Return a copy of slice as a C string. Offers no protection against embedded
    NULL's. Returned string must be freed with gpr_free. */
 GPRAPI char *grpc_slice_to_c_string(grpc_slice s);
 

data/include/grpc/slice_buffer.h

@@ -40,15 +40,15 @@
 extern "C" {
 #endif
 
-/* initialize a slice buffer */
+/** initialize a slice buffer */
 GPRAPI void grpc_slice_buffer_init(grpc_slice_buffer *sb);
-/* destroy a slice buffer - unrefs any held elements */
+/** destroy a slice buffer - unrefs any held elements */
 GPRAPI void grpc_slice_buffer_destroy(grpc_slice_buffer *sb);
-/* Add an element to a slice buffer - takes ownership of the slice.
+/** Add an element to a slice buffer - takes ownership of the slice.
    This function is allowed to concatenate the passed in slice to the end of
    some other slice if desired by the slice buffer. */
 GPRAPI void grpc_slice_buffer_add(grpc_slice_buffer *sb, grpc_slice slice);
-/* add an element to a slice buffer - takes ownership of the slice and returns
+/** add an element to a slice buffer - takes ownership of the slice and returns
    the index of the slice.
    Guarantees that the slice will not be concatenated at the end of another
    slice (i.e. the data for this slice will begin at the first byte of the
@@ -59,31 +59,35 @@ GPRAPI size_t grpc_slice_buffer_add_indexed(grpc_slice_buffer *sb,
                                             grpc_slice slice);
 GPRAPI void grpc_slice_buffer_addn(grpc_slice_buffer *sb, grpc_slice *slices,
                                    size_t n);
-/* add a very small (less than 8 bytes) amount of data to the end of a slice
+/** add a very small (less than 8 bytes) amount of data to the end of a slice
    buffer: returns a pointer into which to add the data */
 GPRAPI uint8_t *grpc_slice_buffer_tiny_add(grpc_slice_buffer *sb, size_t len);
-/* pop the last buffer, but don't unref it */
+/** pop the last buffer, but don't unref it */
 GPRAPI void grpc_slice_buffer_pop(grpc_slice_buffer *sb);
-/* clear a slice buffer, unref all elements */
+/** clear a slice buffer, unref all elements */
 GPRAPI void grpc_slice_buffer_reset_and_unref(grpc_slice_buffer *sb);
-/* swap the contents of two slice buffers */
+/** swap the contents of two slice buffers */
 GPRAPI void grpc_slice_buffer_swap(grpc_slice_buffer *a, grpc_slice_buffer *b);
-/* move all of the elements of src into dst */
+/** move all of the elements of src into dst */
 GPRAPI void grpc_slice_buffer_move_into(grpc_slice_buffer *src,
                                         grpc_slice_buffer *dst);
-/* remove n bytes from the end of a slice buffer */
+/** remove n bytes from the end of a slice buffer */
 GPRAPI void grpc_slice_buffer_trim_end(grpc_slice_buffer *src, size_t n,
                                        grpc_slice_buffer *garbage);
-/* move the first n bytes of src into dst */
+/** move the first n bytes of src into dst */
 GPRAPI void grpc_slice_buffer_move_first(grpc_slice_buffer *src, size_t n,
                                          grpc_slice_buffer *dst);
-/* move the first n bytes of src into dst (copying them) */
+/** move the first n bytes of src into dst without adding references */
+GPRAPI void grpc_slice_buffer_move_first_no_ref(grpc_slice_buffer *src,
+                                                size_t n,
+                                                grpc_slice_buffer *dst);
+/** move the first n bytes of src into dst (copying them) */
 GPRAPI void grpc_slice_buffer_move_first_into_buffer(grpc_exec_ctx *exec_ctx,
                                                      grpc_slice_buffer *src,
                                                      size_t n, void *dst);
-/* take the first slice in the slice buffer */
+/** take the first slice in the slice buffer */
 GPRAPI grpc_slice grpc_slice_buffer_take_first(grpc_slice_buffer *src);
-/* undo the above with (a possibly different) \a slice */
+/** undo the above with (a possibly different) \a slice */
 GPRAPI void grpc_slice_buffer_undo_take_first(grpc_slice_buffer *src,
                                               grpc_slice slice);