GRPC Core  0.11.0.0
 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 {
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 */
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 */
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,
99  int perform_key_canonicalization);
100 /* Unrefs the slice. */
103  size_t length);
104 
105 /* Returns a borrowed slice from the mdstr with its contents base64 encoded
106  and huffman compressed */
108 
109 /* Constructors for grpc_mdelem instances; take a variety of data types that
110  clients may have handy */
112  grpc_mdstr *value);
114  const char *value);
115 /* Unrefs the slices. */
117  gpr_slice value);
119  const char *key,
120  const gpr_uint8 *value,
121  size_t value_length,
122  int canonicalize_key);
123 
124 /* Mutator and accessor for grpc_mdelem user data. The destructor function
125  is used as a type tag and is checked during user_data fetch. */
127  void (*if_destroy_func)(void *));
128 void grpc_mdelem_set_user_data(grpc_mdelem *md, void (*destroy_func)(void *),
129  void *user_data);
130 
131 /* Reference counting */
132 #ifdef GRPC_METADATA_REFCOUNT_DEBUG
133 #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s), __FILE__, __LINE__)
134 #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s), __FILE__, __LINE__)
135 #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s), __FILE__, __LINE__)
136 #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s), __FILE__, __LINE__)
137 grpc_mdstr *grpc_mdstr_ref(grpc_mdstr *s, const char *file, int line);
138 void grpc_mdstr_unref(grpc_mdstr *s, const char *file, int line);
139 grpc_mdelem *grpc_mdelem_ref(grpc_mdelem *md, const char *file, int line);
140 void grpc_mdelem_unref(grpc_mdelem *md, const char *file, int line);
141 #else
142 #define GRPC_MDSTR_REF(s) grpc_mdstr_ref((s))
143 #define GRPC_MDSTR_UNREF(s) grpc_mdstr_unref((s))
144 #define GRPC_MDELEM_REF(s) grpc_mdelem_ref((s))
145 #define GRPC_MDELEM_UNREF(s) grpc_mdelem_unref((s))
150 #endif
151 
152 /* Recover a char* from a grpc_mdstr. The returned string is null terminated.
153  Does not promise that the returned string has no embedded nulls however. */
154 const char *grpc_mdstr_as_c_string(grpc_mdstr *s);
155 
159 
160 /* Batch mode metadata functions.
161  These API's have equivalents above, but allow taking the mdctx just once,
162  performing a bunch of work, and then leaving the mdctx. */
163 
164 /* Lock the metadata context: it's only safe to call _locked_ functions against
165  this context from the calling thread until grpc_mdctx_unlock is called */
166 void grpc_mdctx_lock(grpc_mdctx *ctx);
167 #ifdef GRPC_METADATA_REFCOUNT_DEBUG
168 #define GRPC_MDCTX_LOCKED_MDELEM_UNREF(ctx, elem) \
169  grpc_mdctx_locked_mdelem_unref((ctx), (elem), __FILE__, __LINE__)
170 /* Unref a metadata element */
172  const char *file, int line);
173 #else
174 #define GRPC_MDCTX_LOCKED_MDELEM_UNREF(ctx, elem) \
175  grpc_mdctx_locked_mdelem_unref((ctx), (elem))
176 /* Unref a metadata element */
178 #endif
179 /* Unlock the metadata context */
180 void grpc_mdctx_unlock(grpc_mdctx *ctx);
181 
182 #define GRPC_MDSTR_KV_HASH(k_hash, v_hash) (GPR_ROTL((k_hash), 2) ^ (v_hash))
183 
184 #endif /* GRPC_INTERNAL_CORE_TRANSPORT_METADATA_H */
const char * value
Definition: hpack_table.c:44
grpc_mdstr * grpc_mdstr_ref(grpc_mdstr *s)
Definition: metadata.c:589
uint8_t gpr_uint8
Definition: port_platform.h:310
grpc_mdstr * grpc_mdstr_from_buffer(grpc_mdctx *ctx, const gpr_uint8 *str, size_t length)
Definition: metadata.c:356
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:537
size_t grpc_mdctx_get_mdtab_free_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:614
void grpc_mdctx_unlock(grpc_mdctx *ctx)
Definition: metadata.c:682
void grpc_mdctx_lock(grpc_mdctx *ctx)
Definition: metadata.c:661
void grpc_mdstr_unref(grpc_mdstr *s)
Definition: metadata.c:598
grpc_mdstr *const key
Definition: metadata.h:79
const gpr_uint32 hash
Definition: metadata.h:72
int grpc_mdstr_is_legal_header(grpc_mdstr *s)
Definition: metadata.c:696
Definition: metadata.h:70
uint32_t gpr_uint32
Definition: port_platform.h:312
grpc_mdelem * grpc_mdelem_from_slices(grpc_mdctx *ctx, gpr_slice key, gpr_slice value)
Definition: metadata.c:531
grpc_mdelem * grpc_mdelem_from_strings(grpc_mdctx *ctx, const char *key, const char *value)
Definition: metadata.c:524
size_t grpc_mdctx_get_mdtab_capacity_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:606
void grpc_mdelem_set_user_data(grpc_mdelem *md, void(*destroy_func)(void *), void *user_data)
Definition: metadata.c:628
grpc_mdelem * grpc_mdelem_from_metadata_strings(grpc_mdctx *ctx, grpc_mdstr *key, grpc_mdstr *value)
Definition: metadata.c:472
grpc_mdctx * grpc_mdctx_create_with_seed(gpr_uint32 seed)
Definition: metadata.c:166
grpc_mdelem * grpc_mdelem_ref(grpc_mdelem *md)
Definition: metadata.c:547
void grpc_mdctx_unref(grpc_mdctx *mdctx)
Definition: metadata.c:234
Definition: metadata.c:98
grpc_mdstr * grpc_mdstr_from_slice(grpc_mdctx *ctx, gpr_slice slice)
Definition: metadata.c:349
Definition: metadata.h:78
void grpc_mdctx_ref(grpc_mdctx *mdctx)
Definition: metadata.c:227
const gpr_slice slice
Definition: metadata.h:71
void grpc_mdctx_locked_mdelem_unref(grpc_mdctx *ctx, grpc_mdelem *elem)
Definition: metadata.c:663
grpc_mdstr *const value
Definition: metadata.h:80
int grpc_mdstr_is_bin_suffixed(grpc_mdstr *s)
Definition: metadata.c:712
const char * grpc_mdstr_as_c_string(grpc_mdstr *s)
Definition: metadata.c:585
size_t grpc_mdctx_get_mdtab_count_test_only(grpc_mdctx *mdctx)
Definition: metadata.c:610
grpc_mdstr * grpc_mdstr_from_string(grpc_mdctx *ctx, const char *str, int perform_key_canonicalization)
Definition: metadata.c:314
grpc_mdctx * grpc_mdctx_create(void)
Definition: metadata.c:185
int grpc_mdstr_is_legal_nonbin_header(grpc_mdstr *s)
Definition: metadata.c:704
void grpc_mdelem_unref(grpc_mdelem *md)
Definition: metadata.c:566
void * grpc_mdelem_get_user_data(grpc_mdelem *md, void(*if_destroy_func)(void *))
Definition: metadata.c:618
const char * key
Definition: hpack_table.c:43
Definition: slice.h:79
gpr_slice grpc_mdstr_as_base64_encoded_and_huffman_compressed(grpc_mdstr *str)
Definition: metadata.c:646