GRPC Core 0.10.0.0

- Main Page
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
census.h
Go to the documentation of this file.
1 /*
2 *
3 * Copyright 2015, Google Inc.
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions are
8 * met:
9 *
10 * * Redistributions of source code must retain the above copyright
11 * notice, this list of conditions and the following disclaimer.
12 * * Redistributions in binary form must reproduce the above
13 * copyright notice, this list of conditions and the following disclaimer
14 * in the documentation and/or other materials provided with the
15 * distribution.
16 * * Neither the name of Google Inc. nor the names of its
17 * contributors may be used to endorse or promote products derived from
18 * this software without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 *
32 */
33
34 /* RPC-internal Census API's. These are designed to be generic enough that
35 * they can (ultimately) be used in many different RPC systems (with differing
36 * implementations). */
37
38 #ifndef CENSUS_CENSUS_H
39 #define CENSUS_CENSUS_H
40
41 #include <grpc/grpc.h>
42
43 #ifdef __cplusplus
44 extern "C" {
45 #endif
46
47 /* Identify census features that can be enabled via census_initialize(). */
48 enum census_features {
49 CENSUS_FEATURE_NONE = 0, /* Do not enable census. */
50 CENSUS_FEATURE_TRACING = 1, /* Enable census tracing. */
51 CENSUS_FEATURE_STATS = 2, /* Enable Census stats collection. */
52 CENSUS_FEATURE_CPU = 4, /* Enable Census CPU usage collection. */
53 CENSUS_FEATURE_ALL =
54 CENSUS_FEATURE_TRACING | CENSUS_FEATURE_STATS | CENSUS_FEATURE_CPU
55 };
56
62 int census_initialize(int features);
63 void census_shutdown(void);
64
67 int census_supported(void);
68
70 int census_enabled(void);
71
72 /* Internally, Census relies on a context, which should be propagated across
73 * RPC's. From the RPC subsystems viewpoint, this is an opaque data structure.
74 * A context must be used as the first argument to all other census
75 * functions. Conceptually, contexts should be thought of as specific to
76 * single RPC/thread. The context can be serialized for passing across the
77 * wire. */
78 typedef struct census_context census_context;
79
80 /* This function is called by the RPC subsystem whenever it needs to get a
81 * serialized form of the current census context (presumably to pass across
82 * the wire). Arguments:
83 * 'buffer': pointer to memory into which serialized context will be placed
84 * 'buf_size': size of 'buffer'
85 *
86 * Returns: the number of bytes used in buffer if successful, or 0 if the
87 * buffer is of insufficient size.
88 *
89 * TODO(aveitch): determine how best to communicate required/max buffer size
90 * so caller doesn't have to guess. */
91 size_t census_context_serialize(const census_context *context, char *buffer,
92 size_t buf_size);
93
94 /* Create a new census context, possibly from a serialized buffer. If 'buffer'
95 * is non-NULL, it is assumed that it is a buffer encoded by
96 * census_context_serialize(). If `buffer` is NULL, a new, empty context is
97 * created. The decoded/new contest is returned in 'context'.
98 *
99 * Returns 0 if no errors, non-zero if buffer is incorrectly formatted, in
100 * which case a new empty context will be returned. */
101 int census_context_deserialize(const char *buffer, census_context **context);
102
103 /* The given context is destroyed. Once destroyed, using the context in
104 * future census calls will result in undefined behavior. */
105 void census_context_destroy(census_context *context);
106
107 /* A census statistic to be recorded comprises two parts: an ID for the
108 * particular statistic and the value to be recorded against it. */
109 typedef struct {
110 int id;
111 double value;
112 } census_stat;
113
114 /* Record new stats against the given context. */
115 void census_record_stat(census_context *context, census_stat *stats,
116 size_t nstats);
117
118 #ifdef __cplusplus
119 }
120 #endif
121
122 #endif /* CENSUS_CENSUS_H */
census_context_destroy
void census_context_destroy(census_context *context)
census_context_deserialize
int census_context_deserialize(const char *buffer, census_context **context)
CENSUS_FEATURE_TRACING
Definition: census.h:50
census_initialize
int census_initialize(int features)
Shutdown and startup census subsystem.
CENSUS_FEATURE_CPU
Definition: census.h:52
CENSUS_FEATURE_ALL
Definition: census.h:53
CENSUS_FEATURE_STATS
Definition: census.h:51
census_shutdown
void census_shutdown(void)
census_stat::id
int id
Definition: census.h:110
census_supported
int census_supported(void)
Return the features supported by the current census implementation (not all features will be availabl...
census_stat::value
double value
Definition: census.h:111
census_features
census_features
Definition: census.h:48
census_record_stat
void census_record_stat(census_context *context, census_stat *stats, size_t nstats)
census_enabled
int census_enabled(void)
Return the census features currently enabled.
grpc.h
census_context_serialize
size_t census_context_serialize(const census_context *context, char *buffer, size_t buf_size)
census_stat
Definition: census.h:109
census_context
struct census_context census_context
Definition: census.h:78
CENSUS_FEATURE_NONE
Definition: census.h:49