diff --git a/include/grpc/census.h b/include/grpc/census.h index 7603dfdce1c59141cf1637624bce3965bf1cb37b..a18b997b79b81c4e4dae421c734914531bc4f479 100644 --- a/include/grpc/census.h +++ b/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 {