• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *
3  * Copyright 2015 gRPC authors.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17  */
18 
19 #ifndef GRPC_SLICE_H
20 #define GRPC_SLICE_H
21 
22 #include <grpc/support/port_platform.h>
23 
24 #include <grpc/impl/codegen/slice.h>
25 #include <grpc/support/sync.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30 
31 /** Increment the refcount of s. Requires slice is initialized.
32    Returns s. */
33 GPRAPI grpc_slice grpc_slice_ref(grpc_slice s);
34 
35 /** Decrement the ref count of s.  If the ref count of s reaches zero, all
36    slices sharing the ref count are destroyed, and considered no longer
37    initialized.  If s is ultimately derived from a call to grpc_slice_new(start,
38    len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is
39    ultimately derived from a call to grpc_slice_new_with_len(start, len, dest)
40    where dest!=NULL , then (*dest)(start, len).  Requires s initialized.  */
41 GPRAPI void grpc_slice_unref(grpc_slice s);
42 
43 /** Copy slice - create a new slice that contains the same data as s */
44 GPRAPI grpc_slice grpc_slice_copy(grpc_slice s);
45 
46 /** Create a slice pointing at some data. Calls malloc to allocate a refcount
47    for the object, and arranges that destroy will be called with the pointer
48    passed in at destruction. */
49 GPRAPI grpc_slice grpc_slice_new(void* p, size_t len, void (*destroy)(void*));
50 
51 /** Equivalent to grpc_slice_new, but with a separate pointer that is
52    passed to the destroy function.  This function can be useful when
53    the data is part of a larger structure that must be destroyed when
54    the data is no longer needed. */
55 GPRAPI grpc_slice grpc_slice_new_with_user_data(void* p, size_t len,
56                                                 void (*destroy)(void*),
57                                                 void* user_data);
58 
59 /** Equivalent to grpc_slice_new, but with a two argument destroy function that
60    also takes the slice length. */
61 GPRAPI grpc_slice grpc_slice_new_with_len(void* p, size_t len,
62                                           void (*destroy)(void*, size_t));
63 
64 /** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc()
65    call.
66    Aborts if malloc() fails. */
67 GPRAPI grpc_slice grpc_slice_malloc(size_t length);
68 GPRAPI grpc_slice grpc_slice_malloc_large(size_t length);
69 
70 #define GRPC_SLICE_MALLOC(len) grpc_slice_malloc(len)
71 
72 /** Intern a slice:
73 
74    The return value for two invocations of this function with  the same sequence
75    of bytes is a slice which points to the same memory. */
76 GPRAPI grpc_slice grpc_slice_intern(grpc_slice slice);
77 
78 /** Create a slice by copying a string.
79    Does not preserve null terminators.
80    Equivalent to:
81      size_t len = strlen(source);
82      grpc_slice slice = grpc_slice_malloc(len);
83      memcpy(slice->data, source, len); */
84 GPRAPI grpc_slice grpc_slice_from_copied_string(const char* source);
85 
86 /** Create a slice by copying a buffer.
87    Equivalent to:
88      grpc_slice slice = grpc_slice_malloc(len);
89      memcpy(slice->data, source, len); */
90 GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char* source, size_t len);
91 
92 /** Create a slice pointing to constant memory */
93 GPRAPI grpc_slice grpc_slice_from_static_string(const char* source);
94 
95 /** Create a slice pointing to constant memory */
96 GPRAPI grpc_slice grpc_slice_from_static_buffer(const void* source, size_t len);
97 
98 /** Return a result slice derived from s, which shares a ref count with \a s,
99    where result.data==s.data+begin, and result.length==end-begin. The ref count
100    of \a s is increased by one. Do not assign result back to \a s.
101    Requires s initialized, begin <= end, begin <= s.length, and
102    end <= source->length. */
103 GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end);
104 
105 /** The same as grpc_slice_sub, but without altering the ref count */
106 GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end);
107 
108 /** Splits s into two: modifies s to be s[0:split], and returns a new slice,
109    sharing a refcount with s, that contains s[split:s.length].
110    Requires s intialized, split <= s.length */
111 GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice* s, size_t split);
112 
113 typedef enum {
114   GRPC_SLICE_REF_TAIL = 1,
115   GRPC_SLICE_REF_HEAD = 2,
116   GRPC_SLICE_REF_BOTH = 1 + 2
117 } grpc_slice_ref_whom;
118 
119 /** The same as grpc_slice_split_tail, but with an option to skip altering
120  * refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to
121  * grpc_slice_split_tail(...)) */
122 GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice* s, size_t split,
123                                                   grpc_slice_ref_whom ref_whom);
124 
125 /** Splits s into two: modifies s to be s[split:s.length], and returns a new
126    slice, sharing a refcount with s, that contains s[0:split].
127    Requires s intialized, split <= s.length */
128 GPRAPI grpc_slice grpc_slice_split_head(grpc_slice* s, size_t split);
129 
130 GPRAPI grpc_slice grpc_empty_slice(void);
131 
132 GPRAPI uint32_t grpc_slice_default_hash_impl(grpc_slice s);
133 GPRAPI int grpc_slice_default_eq_impl(grpc_slice a, grpc_slice b);
134 
135 GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b);
136 
137 /** Returns <0 if a < b, ==0 if a == b, >0 if a > b
138    The order is arbitrary, and is not guaranteed to be stable across different
139    versions of the API. */
140 GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b);
141 GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char* b);
142 
143 /** return non-zero if the first blen bytes of a are equal to b */
144 GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void* b, size_t blen);
145 
146 /** return the index of the last instance of \a c in \a s, or -1 if not found */
147 GPRAPI int grpc_slice_rchr(grpc_slice s, char c);
148 GPRAPI int grpc_slice_chr(grpc_slice s, char c);
149 
150 /** return the index of the first occurance of \a needle in \a haystack, or -1
151    if it's not found */
152 GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle);
153 
154 GPRAPI uint32_t grpc_slice_hash(grpc_slice s);
155 
156 /** Do two slices point at the same memory, with the same length
157    If a or b is inlined, actually compares data */
158 GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b);
159 
160 /** Return a slice pointing to newly allocated memory that has the same contents
161  * as \a s */
162 GPRAPI grpc_slice grpc_slice_dup(grpc_slice a);
163 
164 /** Return a copy of slice as a C string. Offers no protection against embedded
165    NULL's. Returned string must be freed with gpr_free. */
166 GPRAPI char* grpc_slice_to_c_string(grpc_slice s);
167 
168 #ifdef __cplusplus
169 }
170 #endif
171 
172 #endif /* GRPC_SLICE_H */
173