Merge pull request #2694 from a-veitch/tag_api

add external tag set API

include/grpc/census.h

@@ -104,6 +104,61 @@ int census_context_deserialize(const char *buffer, census_context **context);
  * future census calls will result in undefined behavior. */
 void census_context_destroy(census_context *context);
 
+/* 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);
+
 /* A census statistic to be recorded comprises two parts: an ID for the
  * particular statistic and the value to be recorded against it. */
 typedef struct {