diff options
author | Alistair Veitch <aveitch@google.com> | 2015-07-28 14:27:28 -0700 |
---|---|---|
committer | Alistair Veitch <aveitch@google.com> | 2015-07-28 14:27:28 -0700 |
commit | f68bf38af4fce75a1d1bc2c7ea7a0109a113caa7 (patch) | |
tree | 73260521068fd8823277ae30a5ab215e7f5ec59e | |
parent | 5c575dd6e4b01cd68cca5d1917b58023dcf4ca0f (diff) |
add external tag set API
-rw-r--r-- | include/grpc/census.h | 55 |
1 files changed, 55 insertions, 0 deletions
diff --git a/include/grpc/census.h b/include/grpc/census.h index 379783905a..eea7ddf728 100644 --- a/include/grpc/census.h +++ b/include/grpc/census.h @@ -100,6 +100,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 + positive values: 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 { |