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/impl/slice_type.h> // IWYU pragma: export 23 #include <grpc/support/port_platform.h> 24 #include <grpc/support/sync.h> 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 /** Increment the refcount of s. Requires slice is initialized. 31 Returns s. */ 32 GPRAPI grpc_slice grpc_slice_ref(grpc_slice s); 33 34 /** Decrement the ref count of s. If the ref count of s reaches zero, all 35 slices sharing the ref count are destroyed, and considered no longer 36 initialized. If s is ultimately derived from a call to grpc_slice_new(start, 37 len, dest) where dest!=NULL , then (*dest)(start) is called, else if s is 38 ultimately derived from a call to grpc_slice_new_with_len(start, len, dest) 39 where dest!=NULL , then (*dest)(start, len). Requires s initialized. */ 40 GPRAPI void grpc_slice_unref(grpc_slice s); 41 42 /** Copy slice - create a new slice that contains the same data as s */ 43 GPRAPI grpc_slice grpc_slice_copy(grpc_slice s); 44 45 /** Create a slice pointing at some data. Calls malloc to allocate a refcount 46 for the object, and arranges that destroy will be called with the pointer 47 passed in at destruction. */ 48 GPRAPI grpc_slice grpc_slice_new(void* p, size_t len, void (*destroy)(void*)); 49 50 /** Equivalent to grpc_slice_new, but with a separate pointer that is 51 passed to the destroy function. This function can be useful when 52 the data is part of a larger structure that must be destroyed when 53 the data is no longer needed. */ 54 GPRAPI grpc_slice grpc_slice_new_with_user_data(void* p, size_t len, 55 void (*destroy)(void*), 56 void* user_data); 57 58 /** Equivalent to grpc_slice_new, but with a two argument destroy function that 59 also takes the slice length. */ 60 GPRAPI grpc_slice grpc_slice_new_with_len(void* p, size_t len, 61 void (*destroy)(void*, size_t)); 62 63 /** Equivalent to grpc_slice_new(malloc(len), len, free), but saves one malloc() 64 call. 65 Aborts if malloc() fails. */ 66 GPRAPI grpc_slice grpc_slice_malloc(size_t length); 67 GPRAPI grpc_slice grpc_slice_malloc_large(size_t length); 68 69 #define GRPC_SLICE_MALLOC(len) grpc_slice_malloc(len) 70 71 /** Create a slice by copying a string. 72 Does not preserve null terminators. 73 Equivalent to: 74 size_t len = strlen(source); 75 grpc_slice slice = grpc_slice_malloc(len); 76 memcpy(slice->data, source, len); */ 77 GPRAPI grpc_slice grpc_slice_from_copied_string(const char* source); 78 79 /** Create a slice by copying a buffer. 80 Equivalent to: 81 grpc_slice slice = grpc_slice_malloc(len); 82 memcpy(slice->data, source, len); */ 83 GPRAPI grpc_slice grpc_slice_from_copied_buffer(const char* source, size_t len); 84 85 /** Create a slice pointing to constant memory */ 86 GPRAPI grpc_slice grpc_slice_from_static_string(const char* source); 87 88 /** Create a slice pointing to constant memory */ 89 GPRAPI grpc_slice grpc_slice_from_static_buffer(const void* source, size_t len); 90 91 /** Return a result slice derived from s, which shares a ref count with \a s, 92 where result.data==s.data+begin, and result.length==end-begin. The ref count 93 of \a s is increased by one. Do not assign result back to \a s. 94 Requires s initialized, begin <= end, begin <= s.length, and 95 end <= source->length. */ 96 GPRAPI grpc_slice grpc_slice_sub(grpc_slice s, size_t begin, size_t end); 97 98 /** The same as grpc_slice_sub, but without altering the ref count */ 99 GPRAPI grpc_slice grpc_slice_sub_no_ref(grpc_slice s, size_t begin, size_t end); 100 101 /** Splits s into two: modifies s to be s[0:split], and returns a new slice, 102 sharing a refcount with s, that contains s[split:s.length]. 103 Requires s initialized, split <= s.length */ 104 GPRAPI grpc_slice grpc_slice_split_tail(grpc_slice* s, size_t split); 105 106 typedef enum { 107 GRPC_SLICE_REF_TAIL = 1, 108 GRPC_SLICE_REF_HEAD = 2, 109 GRPC_SLICE_REF_BOTH = 1 + 2 110 } grpc_slice_ref_whom; 111 112 /** The same as grpc_slice_split_tail, but with an option to skip altering 113 * refcounts (grpc_slice_split_tail_maybe_ref(..., true) is equivalent to 114 * grpc_slice_split_tail(...)) */ 115 GPRAPI grpc_slice grpc_slice_split_tail_maybe_ref(grpc_slice* s, size_t split, 116 grpc_slice_ref_whom ref_whom); 117 118 /** Splits s into two: modifies s to be s[split:s.length], and returns a new 119 slice, sharing a refcount with s, that contains s[0:split]. 120 Requires s initialized, split <= s.length */ 121 GPRAPI grpc_slice grpc_slice_split_head(grpc_slice* s, size_t split); 122 123 GPRAPI grpc_slice grpc_empty_slice(void); 124 125 GPRAPI int grpc_slice_eq(grpc_slice a, grpc_slice b); 126 127 /** Returns <0 if a < b, ==0 if a == b, >0 if a > b 128 The order is arbitrary, and is not guaranteed to be stable across different 129 versions of the API. */ 130 GPRAPI int grpc_slice_cmp(grpc_slice a, grpc_slice b); 131 GPRAPI int grpc_slice_str_cmp(grpc_slice a, const char* b); 132 133 /** return non-zero if the first blen bytes of a are equal to b */ 134 GPRAPI int grpc_slice_buf_start_eq(grpc_slice a, const void* b, size_t blen); 135 136 /** return the index of the last instance of \a c in \a s, or -1 if not found */ 137 GPRAPI int grpc_slice_rchr(grpc_slice s, char c); 138 GPRAPI int grpc_slice_chr(grpc_slice s, char c); 139 140 /** return the index of the first occurrence of \a needle in \a haystack, or -1 141 if it's not found */ 142 GPRAPI int grpc_slice_slice(grpc_slice haystack, grpc_slice needle); 143 144 /** Do two slices point at the same memory, with the same length 145 If a or b is inlined, actually compares data */ 146 GPRAPI int grpc_slice_is_equivalent(grpc_slice a, grpc_slice b); 147 148 /** Return a slice pointing to newly allocated memory that has the same contents 149 * as \a s */ 150 GPRAPI grpc_slice grpc_slice_dup(grpc_slice a); 151 152 /** Return a copy of slice as a C string. Offers no protection against embedded 153 NULL's. Returned string must be freed with gpr_free. */ 154 GPRAPI char* grpc_slice_to_c_string(grpc_slice s); 155 156 #ifdef __cplusplus 157 } 158 #endif 159 160 #endif /* GRPC_SLICE_H */ 161