diff options
author | Hongyu Chen <maxwell-demon@users.noreply.github.com> | 2015-08-12 18:22:16 -0700 |
---|---|---|
committer | Hongyu Chen <maxwell-demon@users.noreply.github.com> | 2015-08-12 18:22:16 -0700 |
commit | 8d428f1e6d0f7b76f8b737ae63f7a74b97279a1d (patch) | |
tree | f0cb7aafe2e4b884b137236918018a3e438344d7 /include/grpc/census.h | |
parent | 82c8ad788bd64f5ab8d45356b83df0b7e5373079 (diff) | |
parent | a178b86668db21ff5c03951d5d9b0b3ad79e9752 (diff) |
Merge pull request #2694 from a-veitch/tag_api
add external tag set API
Diffstat (limited to 'include/grpc/census.h')
-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 7603dfdce1..a18b997b79 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 { |