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
metadata.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 #ifndef GRPC_INTERNAL_CORE_TRANSPORT_METADATA_H
35 #define GRPC_INTERNAL_CORE_TRANSPORT_METADATA_H
36
37 #include <grpc/support/slice.h>
38 #include <grpc/support/useful.h>
39
40 /* This file provides a mechanism for tracking metadata through the grpc stack.
41 It's not intended for consumption outside of the library.
42
43 Metadata is tracked in the context of a grpc_mdctx. For the time being there
44 is one of these per-channel, avoiding cross channel interference with memory
45 use and lock contention.
46
47 The context tracks unique strings (grpc_mdstr) and pairs of strings
48 (grpc_mdelem). Any of these objects can be checked for equality by comparing
49 their pointers. These objects are reference counted.
50
51 grpc_mdelem can additionally store a (non-NULL) user data pointer. This
52 pointer is intended to be used to cache semantic meaning of a metadata
53 element. For example, an OAuth token may cache the credentials it represents
54 and the time at which it expires in the mdelem user data.
55
56 Combining this metadata cache and the hpack compression table allows us to
57 simply lookup complete preparsed objects quickly, incurring a few atomic
58 ops per metadata element on the fast path.
59
60 grpc_mdelem instances MAY live longer than their refcount implies, and are
61 garbage collected periodically, meaning cached data can easily outlive a
62 single request. */
63
64 /* Forward declarations */
65 typedef struct grpc_mdctx grpc_mdctx;
66 typedef struct grpc_mdstr grpc_mdstr;
67 typedef struct grpc_mdelem grpc_mdelem;
68
69 /* if changing this, make identical changes in internal_string in metadata.c */
70 struct grpc_mdstr {
71 const gpr_slice slice;
72 const gpr_uint32 hash;
73 /* there is a private part to this in metadata.c */
74 };
75
76 /* if changing this, make identical changes in internal_metadata in
77 metadata.c */
78 struct grpc_mdelem {
79 grpc_mdstr *const key;
80 grpc_mdstr *const value;
81 /* there is a private part to this in metadata.c */
82 };
83
84 /* Create/orphan a metadata context */
85 grpc_mdctx *grpc_mdctx_create(void);
86 grpc_mdctx *grpc_mdctx_create_with_seed(gpr_uint32 seed);
87 void grpc_mdctx_ref(grpc_mdctx *mdctx);
88 void grpc_mdctx_unref(grpc_mdctx *mdctx);
89
90 /* Test only accessors to internal state - only for testing this code - do not
91 rely on it outside of metadata_test.c */
92 size_t grpc_mdctx_get_mdtab_capacity_test_only(grpc_mdctx *mdctx);
93 size_t grpc_mdctx_get_mdtab_count_test_only(grpc_mdctx *mdctx);
94 size_t grpc_mdctx_get_mdtab_free_test_only(grpc_mdctx *mdctx);
95
96 /* Constructors for grpc_mdstr instances; take a variety of data types that
97 clients may have handy */
98 grpc_mdstr *grpc_mdstr_from_string(grpc_mdctx *ctx, const char *str, int perform_key_canonicalization);
99 /* Unrefs the slice. */
100 grpc_mdstr *grpc_mdstr_from_slice(grpc_mdctx *ctx, gpr_slice slice);
101 grpc_mdstr *grpc_mdstr_from_buffer(grpc_mdctx *ctx, const gpr_uint8 *str,
102 size_t length);
103
104 /* Returns a borrowed slice from the mdstr with its contents base64 encoded
105 and huffman compressed */
106 gpr_slice grpc_mdstr_as_base64_encoded_and_huffman_compressed(grpc_mdstr *str);
107
108 /* Constructors for grpc_mdelem instances; take a variety of data types that
109 clients may have handy */
110 grpc_mdelem *grpc_mdelem_from_metadata_strings(grpc_mdctx *ctx, grpc_mdstr *key,
111 grpc_mdstr *value);
112 grpc_mdelem *grpc_mdelem_from_strings(grpc_mdctx *ctx, const char *key,
113 const char *value);
114 /* Unrefs the slices. */
115 grpc_mdelem *grpc_mdelem_from_slices(grpc_mdctx *ctx, gpr_slice key,
116 gpr_slice value);
117 grpc_mdelem *grpc_mdelem_from_string_and_buffer(grpc_mdctx *ctx,
118 const char *key,
119 const gpr_uint8 *value,
120 size_t value_length,
121 int canonicalize_key);
122
123 /* Mutator and accessor for grpc_mdelem user data. The destructor function
124 is used as a type tag and is checked during user_data fetch. */
125 void *grpc_mdelem_get_user_data(grpc_mdelem *md,
126 void (*if_destroy_func)(void *));
127 void grpc_mdelem_set_user_data(grpc_mdelem *md, void (*destroy_func)(void *),
128 void *user_data);
129
130 /* Reference counting */
131 #ifdef GRPC_METADATA_REFCOUNT_DEBUG
132 #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s), __FILE__, __LINE__)
133 #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s), __FILE__, __LINE__)
134 #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s), __FILE__, __LINE__)
135 #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s), __FILE__, __LINE__)
136 grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s, const char *file, int line);
137 void grpc_mdstr_unref(grpc_mdstr *s, const char *file, int line);
138 grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md, const char *file, int line);
139 void grpc_mdelem_unref(grpc_mdelem *md, const char *file, int line);
140 #else
141 #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s))
142 #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s))
143 #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s))
144 #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s))
145 grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s);
146 void grpc_mdstr_unref(grpc_mdstr *s);
147 grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md);
148 void grpc_mdelem_unref(grpc_mdelem *md);
149 #endif
150
151 /* Recover a char* from a grpc_mdstr. The returned string is null terminated.
152 Does not promise that the returned string has no embedded nulls however. */
153 const char *grpc_mdstr_as_c_string(grpc_mdstr *s);
154
155 int grpc_mdstr_is_legal_header(grpc_mdstr *s);
156 int grpc_mdstr_is_bin_suffixed(grpc_mdstr *s);
157
158 /* Batch mode metadata functions.
159 These API's have equivalents above, but allow taking the mdctx just once,
160 performing a bunch of work, and then leaving the mdctx. */
161
162 /* Lock the metadata context: it's only safe to call _locked_ functions against
163 this context from the calling thread until grpc_mdctx_unlock is called */
164 void grpc_mdctx_lock(grpc_mdctx *ctx);
165 #ifdef GRPC_METADATA_REFCOUNT_DEBUG
166 #define GRPC_MDCTX_LOCKED_MDELEM_UNREF(ctx, elem) \
167 grpc_mdctx_locked_mdelem_unref((ctx), (elem), __FILE__, __LINE__)
168 /* Unref a metadata element */
169 void grpc_mdctx_locked_mdelem_unref(grpc_mdctx *ctx, grpc_mdelem *elem,
170 const char *file, int line);
171 #else
172 #define GRPC_MDCTX_LOCKED_MDELEM_UNREF(ctx, elem) \
173 grpc_mdctx_locked_mdelem_unref((ctx), (elem))
174 /* Unref a metadata element */
175 void grpc_mdctx_locked_mdelem_unref(grpc_mdctx *ctx, grpc_mdelem *elem);
176 #endif
177 /* Unlock the metadata context */
178 void grpc_mdctx_unlock(grpc_mdctx *ctx);
179
180 #define GRPC_MDSTR_KV_HASH(k_hash, v_hash) (GPR_ROTL((k_hash), 2) ^ (v_hash))
181
182 #endif /* GRPC_INTERNAL_CORE_TRANSPORT_METADATA_H */
value
const char * value
Definition: hpack_table.c:44
grpc_mdstr_ref
grpc_mdstr * grpc_mdstr_ref(grpc_mdstr *s)
Definition: metadata.c:586
gpr_uint8
uint8_t gpr_uint8
Definition: port_platform.h:307
grpc_mdstr_from_buffer
grpc_mdstr * grpc_mdstr_from_buffer(grpc_mdctx *ctx, const gpr_uint8 *str, size_t length)
Definition: metadata.c:353
grpc_mdelem_from_string_and_buffer
grpc_mdelem * grpc_mdelem_from_string_and_buffer(grpc_mdctx *ctx, const char *key, const gpr_uint8 *value, size_t value_length, int canonicalize_key)
Definition: metadata.c:534
grpc_mdctx_get_mdtab_free_test_only
size_t grpc_mdctx_get_mdtab_free_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:611
grpc_mdctx_unlock
void grpc_mdctx_unlock(grpc_mdctx *ctx)
Definition: metadata.c:679
grpc_mdctx_lock
void grpc_mdctx_lock(grpc_mdctx *ctx)
Definition: metadata.c:658
grpc_mdstr_unref
void grpc_mdstr_unref(grpc_mdstr *s)
Definition: metadata.c:595
grpc_mdelem::key
grpc_mdstr *const key
Definition: metadata.h:79
grpc_mdstr::hash
const gpr_uint32 hash
Definition: metadata.h:72
grpc_mdstr_is_legal_header
int grpc_mdstr_is_legal_header(grpc_mdstr *s)
Definition: metadata.c:681
grpc_mdstr
Definition: metadata.h:70
gpr_uint32
uint32_t gpr_uint32
Definition: port_platform.h:309
useful.h
grpc_mdelem_from_slices
grpc_mdelem * grpc_mdelem_from_slices(grpc_mdctx *ctx, gpr_slice key, gpr_slice value)
Definition: metadata.c:528
grpc_mdelem_from_strings
grpc_mdelem * grpc_mdelem_from_strings(grpc_mdctx *ctx, const char *key, const char *value)
Definition: metadata.c:521
grpc_mdctx_get_mdtab_capacity_test_only
size_t grpc_mdctx_get_mdtab_capacity_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:603
grpc_mdelem_set_user_data
void grpc_mdelem_set_user_data(grpc_mdelem *md, void(*destroy_func)(void *), void *user_data)
Definition: metadata.c:625
grpc_mdelem_from_metadata_strings
grpc_mdelem * grpc_mdelem_from_metadata_strings(grpc_mdctx *ctx, grpc_mdstr *key, grpc_mdstr *value)
Definition: metadata.c:469
grpc_mdctx_create_with_seed
grpc_mdctx * grpc_mdctx_create_with_seed(gpr_uint32 seed)
Definition: metadata.c:164
grpc_mdelem_ref
grpc_mdelem * grpc_mdelem_ref(grpc_mdelem *md)
Definition: metadata.c:544
grpc_mdctx_unref
void grpc_mdctx_unref(grpc_mdctx *mdctx)
Definition: metadata.c:232
grpc_mdctx
Definition: metadata.c:98
grpc_mdstr_from_slice
grpc_mdstr * grpc_mdstr_from_slice(grpc_mdctx *ctx, gpr_slice slice)
Definition: metadata.c:346
grpc_mdelem
Definition: metadata.h:78
grpc_mdctx_ref
void grpc_mdctx_ref(grpc_mdctx *mdctx)
Definition: metadata.c:225
grpc_mdstr::slice
const gpr_slice slice
Definition: metadata.h:71
grpc_mdctx_locked_mdelem_unref
void grpc_mdctx_locked_mdelem_unref(grpc_mdctx *ctx, grpc_mdelem *elem)
Definition: metadata.c:660
grpc_mdelem::value
grpc_mdstr *const value
Definition: metadata.h:80
slice.h
grpc_mdstr_is_bin_suffixed
int grpc_mdstr_is_bin_suffixed(grpc_mdstr *s)
Definition: metadata.c:691
grpc_mdstr_as_c_string
const char * grpc_mdstr_as_c_string(grpc_mdstr *s)
Definition: metadata.c:582
grpc_mdctx_get_mdtab_count_test_only
size_t grpc_mdctx_get_mdtab_count_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:607
grpc_mdstr_from_string
grpc_mdstr * grpc_mdstr_from_string(grpc_mdctx *ctx, const char *str, int perform_key_canonicalization)
Definition: metadata.c:312
grpc_mdctx_create
grpc_mdctx * grpc_mdctx_create(void)
Definition: metadata.c:183
grpc_mdelem_unref
void grpc_mdelem_unref(grpc_mdelem *md)
Definition: metadata.c:563
grpc_mdelem_get_user_data
void * grpc_mdelem_get_user_data(grpc_mdelem *md, void(*if_destroy_func)(void *))
Definition: metadata.c:615
key
const char * key
Definition: hpack_table.c:43
gpr_slice
Definition: slice.h:79
grpc_mdstr_as_base64_encoded_and_huffman_compressed
gpr_slice grpc_mdstr_as_base64_encoded_and_huffman_compressed(grpc_mdstr *str)
Definition: metadata.c:643