awesome-grpc-that-works 0.12.2 → 0.14.0.dev

data/include/grpc/byte_buffer.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright 2015, Google Inc.
+ * Copyright 2015-2016, Google Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -34,87 +34,6 @@
 #ifndef GRPC_BYTE_BUFFER_H
 #define GRPC_BYTE_BUFFER_H
 
-#include <grpc/compression.h>
-#include <grpc/support/slice_buffer.h>
-
-#ifdef __cplusplus
-extern "C" {
-#endif
-
-typedef enum {
-  GRPC_BB_RAW
-  /* Future types may include GRPC_BB_PROTOBUF, etc. */
-} grpc_byte_buffer_type;
-
-struct grpc_byte_buffer {
-  void *reserved;
-  grpc_byte_buffer_type type;
-  union {
-    struct {
-      void *reserved[8];
-    } reserved;
-    struct {
-      grpc_compression_algorithm compression;
-      gpr_slice_buffer slice_buffer;
-    } raw;
-  } data;
-};
-typedef struct grpc_byte_buffer grpc_byte_buffer;
-
-/** Returns a RAW byte buffer instance over the given slices (up to \a nslices).
- *
- * Increases the reference count for all \a slices processed. The user is
- * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
-grpc_byte_buffer *grpc_raw_byte_buffer_create(gpr_slice *slices,
-                                              size_t nslices);
-
-/** Returns a *compressed* RAW byte buffer instance over the given slices (up to
- * \a nslices). The \a compression argument defines the compression algorithm
- * used to generate the data in \a slices.
- *
- * Increases the reference count for all \a slices processed. The user is
- * responsible for invoking grpc_byte_buffer_destroy on the returned instance.*/
-grpc_byte_buffer *grpc_raw_compressed_byte_buffer_create(
-    gpr_slice *slices, size_t nslices, grpc_compression_algorithm compression);
-
-/** Copies input byte buffer \a bb.
- *
- * Increases the reference count of all the source slices. The user is
- * responsible for calling grpc_byte_buffer_destroy over the returned copy. */
-grpc_byte_buffer *grpc_byte_buffer_copy(grpc_byte_buffer *bb);
-
-/** Returns the size of the given byte buffer, in bytes. */
-size_t grpc_byte_buffer_length(grpc_byte_buffer *bb);
-
-/** Destroys \a byte_buffer deallocating all its memory. */
-void grpc_byte_buffer_destroy(grpc_byte_buffer *byte_buffer);
-
-/** Reader for byte buffers. Iterates over slices in the byte buffer */
-struct grpc_byte_buffer_reader;
-typedef struct grpc_byte_buffer_reader grpc_byte_buffer_reader;
-
-/** Initialize \a reader to read over \a buffer */
-void grpc_byte_buffer_reader_init(grpc_byte_buffer_reader *reader,
-                                  grpc_byte_buffer *buffer);
-
-/** Cleanup and destroy \a reader */
-void grpc_byte_buffer_reader_destroy(grpc_byte_buffer_reader *reader);
-
-/** Updates \a slice with the next piece of data from from \a reader and returns
- * 1. Returns 0 at the end of the stream. Caller is responsible for calling
- * gpr_slice_unref on the result. */
-int grpc_byte_buffer_reader_next(grpc_byte_buffer_reader *reader,
-                                 gpr_slice *slice);
-
-/** Merge all data from \a reader into single slice */
-gpr_slice grpc_byte_buffer_reader_readall(grpc_byte_buffer_reader *reader);
-
-/** Returns a RAW byte buffer instance from the output of \a reader. */
-grpc_byte_buffer *grpc_raw_byte_buffer_from_reader(
-    grpc_byte_buffer_reader *reader);
-
-#ifdef __cplusplus
-}
-#endif
+#include <grpc/impl/codegen/byte_buffer.h>
 
 #endif /* GRPC_BYTE_BUFFER_H */

data/include/grpc/census.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright 2015, Google Inc.
+ * Copyright 2015-2016, Google Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -59,39 +59,142 @@ enum census_features {
  * census_initialize() will return a non-zero value. It is an error to call
  * census_initialize() more than once (without an intervening
  * census_shutdown()). */
-int census_initialize(int features);
-void census_shutdown(void);
+CENSUSAPI int census_initialize(int features);
+CENSUSAPI void census_shutdown(void);
 
 /** Return the features supported by the current census implementation (not all
  * features will be available on all platforms). */
-int census_supported(void);
+CENSUSAPI int census_supported(void);
 
 /** Return the census features currently enabled. */
-int census_enabled(void);
+CENSUSAPI int census_enabled(void);
 
 /**
-  Context is a handle used by census to represent the current tracing and
-  tagging information. Contexts should be propagated across RPC's. Contexts
-  are created by any of the census_start_*_op() functions. A context is
-  typically used as argument to most census functions. Conceptually, contexts
-  should be thought of as specific to single RPC/thread. The context can be
-  serialized for passing across the wire, via census_context_serialize().
-*/
+  A Census Context is a handle used by Census to represent the current tracing
+  and stats collection information. Contexts should be propagated across RPC's
+  (this is the responsibility of the local RPC system). A context is typically
+  used as the first argument to most census functions. Conceptually, they
+  should be thought of as specific to a single RPC/thread. The user visible
+  context representation is that of a collection of key:value string pairs,
+  each of which is termed a 'tag'; these form the basis against which Census
+  metrics will be recorded. Keys are unique within a context. */
 typedef struct census_context census_context;
 
-/* This function is called by the RPC subsystem whenever it needs to get a
- * serialized form of the current census context (presumably to pass across
- * the wire). Arguments:
- * 'buffer': pointer to memory into which serialized context will be placed
- * 'buf_size': size of 'buffer'
- *
- * Returns: the number of bytes used in buffer if successful, or 0 if the
- * buffer is of insufficient size.
- *
- * TODO(aveitch): determine how best to communicate required/max buffer size
- * so caller doesn't have to guess. */
-size_t census_context_serialize(const census_context *context, char *buffer,
-                                size_t buf_size);
+/* A tag is a key:value pair. Both keys and values are nil-terminated strings,
+   containing printable ASCII characters (decimal 32-126). Keys must be at
+   least one character in length. Both keys and values can have at most
+   CENSUS_MAX_TAG_KB_LEN characters (including the terminating nil). The
+   maximum number of tags that can be propagated is
+   CENSUS_MAX_PROPAGATED_TAGS. Users should also remember that some systems
+   may have limits on, e.g., the number of bytes that can be transmitted as
+   metadata, and that larger tags means more memory consumed and time in
+   processing. */
+typedef struct {
+  const char *key;
+  const char *value;
+  uint8_t flags;
+} census_tag;
+
+/* Maximum length of a tag's key or value. */
+#define CENSUS_MAX_TAG_KV_LEN 255
+/* Maximum number of propagatable tags. */
+#define CENSUS_MAX_PROPAGATED_TAGS 255
+
+/* Tag flags. */
+#define CENSUS_TAG_PROPAGATE 1 /* Tag should be propagated over RPC */
+#define CENSUS_TAG_STATS 2     /* Tag will be used for statistics aggregation */
+#define CENSUS_TAG_RESERVED 4  /* Reserved for internal use. */
+/* Flag values 4,8,16,32,64,128 are reserved for future/internal use. Clients
+   should not use or rely on their values. */
+
+#define CENSUS_TAG_IS_PROPAGATED(flags) (flags & CENSUS_TAG_PROPAGATE)
+#define CENSUS_TAG_IS_STATS(flags) (flags & CENSUS_TAG_STATS)
+
+/* An instance of this structure is kept by every context, and records the
+   basic information associated with the creation of that context. */
+typedef struct {
+  int n_propagated_tags; /* number of propagated tags */
+  int n_local_tags;      /* number of non-propagated (local) tags */
+  int n_deleted_tags;    /* number of tags that were deleted */
+  int n_added_tags;      /* number of tags that were added */
+  int n_modified_tags;   /* number of tags that were modified */
+  int n_invalid_tags;    /* number of tags with bad keys or values (e.g.
+                            longer than CENSUS_MAX_TAG_KV_LEN) */
+  int n_ignored_tags;    /* number of tags ignored because of
+                            CENSUS_MAX_PROPAGATED_TAGS limit. */
+} census_context_status;
+
+/* Create a new context, adding and removing tags from an existing context.
+   This will copy all tags from the 'tags' input, so it is recommended
+   to add as many tags in a single operation as is practical for the client.
+   @param base Base context to build upon. Can be NULL.
+   @param tags A set of tags to be added/changed/deleted. Tags with keys that
+   are in 'tags', but not 'base', are added to the context. Keys that are in
+   both 'tags' and 'base' will have their value/flags modified. Tags with keys
+   in both, but with NULL values, will be deleted from the context. Tags with
+   invalid (too long or short) keys or values will be ignored.
+   If adding a tag will result in more than CENSUS_MAX_PROPAGATED_TAGS in either
+   binary or non-binary tags, they will be ignored, as will deletions of
+   tags that don't exist.
+   @param ntags number of tags in 'tags'
+   @param status If not NULL, will return a pointer to a census_context_status
+   structure containing information about the new context and status of the
+   tags used in its creation.
+   @return A new, valid census_context.
+*/
+CENSUSAPI census_context *census_context_create(
+    const census_context *base, const census_tag *tags, int ntags,
+    census_context_status const **status);
+
+/* Destroy a context. Once this function has been called, the context cannot
+   be reused. */
+CENSUSAPI void census_context_destroy(census_context *context);
+
+/* Get a pointer to the original status from the context creation. */
+CENSUSAPI const census_context_status *census_context_get_status(
+    const census_context *context);
+
+/* Structure used for iterating over the tegs in a context. API clients should
+   not use or reference internal fields - neither their contents or
+   presence/absence are guaranteed. */
+typedef struct {
+  const census_context *context;
+  int base;
+  int index;
+  char *kvm;
+} census_context_iterator;
+
+/* Initialize a census_tag_iterator. Must be called before first use. */
+CENSUSAPI void census_context_initialize_iterator(
+    const census_context *context, census_context_iterator *iterator);
+
+/* Get the contents of the "next" tag in the context. If there are no more
+   tags, returns 0 (and 'tag' contents will be unchanged), otherwise returns 1.
+   */
+CENSUSAPI int census_context_next_tag(census_context_iterator *iterator,
+                                      census_tag *tag);
+
+/* Get a context tag by key. Returns 0 if the key is not present. */
+CENSUSAPI int census_context_get_tag(const census_context *context,
+                                     const char *key, census_tag *tag);
+
+/* Tag set encode/decode functionality. These functionas are intended
+   for use by RPC systems only, for purposes of transmitting/receiving contexts.
+   */
+
+/* Encode a context into a buffer.
+   @param context context to be encoded
+   @param buffer buffer into which the context will be encoded.
+   @param buf_size number of available bytes in buffer.
+   @return The number of buffer bytes consumed for the encoded context, or
+           zero if the buffer was of insufficient size. */
+CENSUSAPI size_t census_context_encode(const census_context *context,
+                                       char *buffer, size_t buf_size);
+
+/* Decode context buffer encoded with census_context_encode(). Returns NULL
+   if there is an error in parsing either buffer. */
+CENSUSAPI census_context *census_context_decode(const char *buffer,
+                                                size_t size);
 
 /* Distributed traces can have a number of options. */
 enum census_trace_mask_values {
@@ -101,10 +204,10 @@ enum census_trace_mask_values {
 
 /** Get the current trace mask associated with this context. The value returned
     will be the logical or of census_trace_mask_values values. */
-int census_trace_mask(const census_context *context);
+CENSUSAPI int census_trace_mask(const census_context *context);
 
 /** Set the trace mask associated with a context. */
-void census_set_trace_mask(int trace_mask);
+CENSUSAPI void census_set_trace_mask(int trace_mask);
 
 /* The concept of "operation" is a fundamental concept for Census. In an RPC
    system, and operation typcially represents a single RPC, or a significant
@@ -152,7 +255,7 @@ typedef struct {
 
   @return A timestamp representing the operation start time.
 */
-census_timestamp census_start_rpc_op_timestamp(void);
+CENSUSAPI census_timestamp census_start_rpc_op_timestamp(void);
 
 /**
   Represent functions to map RPC name ID to service/method names. Census
@@ -166,8 +269,8 @@ census_timestamp census_start_rpc_op_timestamp(void);
   functions, maybe it should be set once at census initialization.
 */
 typedef struct {
-  const char *(*get_rpc_service_name)(gpr_int64 id);
-  const char *(*get_rpc_method_name)(gpr_int64 id);
+  const char *(*get_rpc_service_name)(int64_t id);
+  const char *(*get_rpc_method_name)(int64_t id);
 } census_rpc_name_info;
 
 /**
@@ -204,15 +307,16 @@ typedef struct {
 
    @return A new census context.
  */
-census_context *census_start_client_rpc_op(
-    const census_context *context, gpr_int64 rpc_name_id,
+CENSUSAPI census_context *census_start_client_rpc_op(
+    const census_context *context, int64_t rpc_name_id,
     const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
     const census_timestamp *start_time);
 
 /**
   Add peer information to a context representing a client RPC operation.
 */
-void census_set_rpc_client_peer(census_context *context, const char *peer);
+CENSUSAPI void census_set_rpc_client_peer(census_context *context,
+                                          const char *peer);
 
 /**
    Start a server RPC operation. Returns a new context to be used in future
@@ -232,8 +336,8 @@ void census_set_rpc_client_peer(census_context *context, const char *peer);
 
    @return A new census context.
  */
-census_context *census_start_server_rpc_op(
-    const char *buffer, gpr_int64 rpc_name_id,
+CENSUSAPI census_context *census_start_server_rpc_op(
+    const char *buffer, int64_t rpc_name_id,
     const census_rpc_name_info *rpc_name_info, const char *peer, int trace_mask,
     census_timestamp *start_time);
 
@@ -262,8 +366,9 @@ census_context *census_start_server_rpc_op(
 
    @return A new census context.
  */
-census_context *census_start_op(census_context *context, const char *family,
-                                const char *name, int trace_mask);
+CENSUSAPI census_context *census_start_op(census_context *context,
+                                          const char *family, const char *name,
+                                          int trace_mask);
 
 /**
   End an operation started by any of the census_start_*_op*() calls. The
@@ -274,10 +379,10 @@ census_context *census_start_op(census_context *context, const char *family,
   @param status status associated with the operation. Not interpreted by
                 census.
 */
-void census_end_op(census_context *context, int status);
+CENSUSAPI void census_end_op(census_context *context, int status);
 
-#define CENSUS_TRACE_RECORD_START_OP ((gpr_uint32)0)
-#define CENSUS_TRACE_RECORD_END_OP ((gpr_uint32)1)
+#define CENSUS_TRACE_RECORD_START_OP ((uint32_t)0)
+#define CENSUS_TRACE_RECORD_END_OP ((uint32_t)1)
 
 /** Insert a trace record into the trace stream. The record consists of an
     arbitrary size buffer, the size of which is provided in 'n'.
@@ -286,15 +391,15 @@ void census_end_op(census_context *context, int status);
     @param buffer Pointer to buffer to use
     @param n Number of bytes in buffer
 */
-void census_trace_print(census_context *context, gpr_uint32 type,
-                        const char *buffer, size_t n);
+CENSUSAPI void census_trace_print(census_context *context, uint32_t type,
+                                  const char *buffer, size_t n);
 
 /** Trace record. */
 typedef struct {
   census_timestamp timestamp; /* Time of record creation */
-  gpr_uint64 trace_id;        /* Trace ID associated with record */
-  gpr_uint64 op_id;           /* Operation ID associated with record */
-  gpr_uint32 type;            /* Type (as used in census_trace_print() */
+  uint64_t trace_id;          /* Trace ID associated with record */
+  uint64_t op_id;             /* Operation ID associated with record */
+  uint32_t type;              /* Type (as used in census_trace_print() */
   const char *buffer;         /* Buffer (from census_trace_print() */
   size_t buf_size;            /* Number of bytes inside buffer */
 } census_trace_record;
@@ -308,7 +413,7 @@ typedef struct {
          while scanning is ongoing.
   @returns 0 on success, non-zero on failure (e.g. if a scan is already ongoing)
 */
-int census_trace_scan_start(int consume);
+CENSUSAPI int census_trace_scan_start(int consume);
 
 /** Get a trace record. The data pointed to by the trace buffer is guaranteed
     stable until the next census_get_trace_record() call (if the consume
@@ -319,65 +424,10 @@ int census_trace_scan_start(int consume);
            census_trace_scan_start()), 0 if there is no more trace data (and
            trace_record will not be modified) or 1 otherwise.
 */
-int census_get_trace_record(census_trace_record *trace_record);
+CENSUSAPI int census_get_trace_record(census_trace_record *trace_record);
 
 /** End a scan previously started by census_trace_scan_start() */
-void census_trace_scan_end();
-
-/* Max number of characters in tag key */
-#define CENSUS_MAX_TAG_KEY_LENGTH 20
-/* Max number of tag value characters */
-#define CENSUS_MAX_TAG_VALUE_LENGTH 50
-
-/* A Census tag set is a collection of key:value string pairs; these form the
-   basis against which Census metrics will be recorded. Keys are unique within
-   a tag set. All contexts have an associated tag set. */
-typedef struct census_tag_set census_tag_set;
-
-/* Returns a pointer to a newly created, empty tag set. If size_hint > 0,
-   indicates that the tag set is intended to hold approximately that number
-   of tags. */
-census_tag_set *census_tag_set_create(size_t size_hint);
-
-/* Add a new tag key/value to an existing tag set; if the tag key already exists
-   in the tag set, then its value is overwritten with the new one. Can also be
-   used to delete a tag, by specifying a NULL value. If key is NULL, returns
-   the number of tags in the tag set.
-   Return values:
-   -1: invalid length key or value
-   non-negative value: the number of tags in the tag set. */
-int census_tag_set_add(census_tag_set *tags, const char *key,
-                       const char *value);
-
-/* Destroys a tag set. This function must be called to prevent memory leaks.
-   Once called, the tag set cannot be used again. */
-void census_tag_set_destroy(census_tag_set *tags);
-
-/* Get a contexts tag set. */
-census_tag_set *census_context_tag_set(census_context *context);
-
-/* A read-only representation of a tag for use by census clients. */
-typedef struct {
-  size_t key_len;    /* Number of bytes in tag key. */
-  const char *key;   /* A pointer to the tag key. May not be null-terminated. */
-  size_t value_len;  /* Number of bytes in tag value. */
-  const char *value; /* Pointer to the tag value. May not be null-terminated. */
-} census_tag_const;
-
-/* Used to iterate through a tag sets contents. */
-typedef struct census_tag_set_iterator census_tag_set_iterator;
-
-/* Open a tag set for iteration. The tag set must not be modified while
-   iteration is ongoing. Returns an iterator for use in following functions. */
-census_tag_set_iterator *census_tag_set_open(census_tag_set *tags);
-
-/* Get the next tag in the tag set, by writing into the 'tag' argument. Returns
-   1 if there is a "next" tag, 0 if there are no more tags. */
-int census_tag_set_next(census_tag_set_iterator *it, census_tag_const *tag);
-
-/* Close an iterator opened by census_tag_set_open(). The iterator will be
-   invalidated, and should not be used once close is called. */
-void census_tag_set_close(census_tag_set_iterator *it);
+CENSUSAPI void census_trace_scan_end();
 
 /* Core stats collection API's. The following concepts are used:
    * Aggregation: A collection of values. Census supports the following
@@ -403,13 +453,13 @@ void census_tag_set_close(census_tag_set_iterator *it);
 /* A single value to be recorded comprises two parts: an ID for the particular
  * metric and the value to be recorded against it. */
 typedef struct {
-  gpr_uint32 metric_id;
+  uint32_t metric_id;
   double value;
 } census_value;
 
 /* Record new usage values against the given context. */
-void census_record_values(census_context *context, census_value *values,
-                          size_t nvalues);
+CENSUSAPI void census_record_values(census_context *context,
+                                    census_value *values, size_t nvalues);
 
 /** Type representing a particular aggregation */
 typedef struct census_aggregation_ops census_aggregation_ops;
@@ -424,8 +474,7 @@ extern census_aggregation_ops census_agg_window;
     construction via census_define_view(). */
 typedef struct {
   const census_aggregation_ops *ops;
-  const void *
-      create_arg; /* Argument to be used for aggregation initialization. */
+  const void *create_arg; /* Aaggregation initialization argument. */
 } census_aggregation;
 
 /** A census view type. Opaque. */
@@ -433,36 +482,39 @@ typedef struct census_view census_view;
 
 /** Create a new view.
   @param metric_id Metric with which this view is associated.
-  @param tags tags that define the view
+  @param tags tags that define the view.
   @param aggregations aggregations to associate with the view
   @param naggregations number of aggregations
 
   @return A new census view
 */
-census_view *census_view_create(gpr_uint32 metric_id,
-                                const census_tag_set *tags,
-                                const census_aggregation *aggregations,
-                                size_t naggregations);
+
+/* TODO(aveitch): consider if context is the right argument type to pass in
+   tags. */
+CENSUSAPI census_view *census_view_create(
+    uint32_t metric_id, const census_context *tags,
+    const census_aggregation *aggregations, size_t naggregations);
 
 /** Destroy a previously created view. */
-void census_view_delete(census_view *view);
+CENSUSAPI void census_view_delete(census_view *view);
 
 /** Metric ID associated with a view */
-size_t census_view_metric(const census_view *view);
+CENSUSAPI size_t census_view_metric(const census_view *view);
 
 /** Number of aggregations associated with view. */
-size_t census_view_naggregations(const census_view *view);
+CENSUSAPI size_t census_view_naggregations(const census_view *view);
 
 /** Get tags associated with view. */
-const census_tag_set *census_view_tags(const census_view *view);
+CENSUSAPI const census_context *census_view_tags(const census_view *view);
 
 /** Get aggregation descriptors associated with a view. */
-const census_aggregation *census_view_aggregrations(const census_view *view);
+CENSUSAPI const census_aggregation *census_view_aggregrations(
+    const census_view *view);
 
 /** Holds all the aggregation data for a particular view instantiation. Forms
   part of the data returned by census_view_data(). */
 typedef struct {
-  const census_tag_set *tags; /* Tags for this set of aggregations. */
+  const census_context *tags; /* Tags for this set of aggregations. */
   const void **data; /* One data set for every aggregation in the view. */
 } census_view_aggregation_data;
 
@@ -476,10 +528,10 @@ typedef struct {
   @param view View from which to get data.
   @return Full set of data for all aggregations for the view.
 */
-const census_view_data *census_view_get_data(const census_view *view);
+CENSUSAPI const census_view_data *census_view_get_data(const census_view *view);
 
 /** Reset all view data to zero for the specified view */
-void census_view_reset(census_view *view);
+CENSUSAPI void census_view_reset(census_view *view);
 
 #ifdef __cplusplus
 }