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_IMPL_CODEGEN_SLICE_H 20 #define GRPC_IMPL_CODEGEN_SLICE_H 21 22 #include <grpc/impl/codegen/port_platform.h> 23 24 #include <stddef.h> 25 26 #include <grpc/impl/codegen/gpr_slice.h> 27 28 typedef struct grpc_slice grpc_slice; 29 30 /** Slice API 31 32 A slice represents a contiguous reference counted array of bytes. 33 It is cheap to take references to a slice, and it is cheap to create a 34 slice pointing to a subset of another slice. 35 36 The data-structure for slices is exposed here to allow non-gpr code to 37 build slices from whatever data they have available. 38 39 When defining interfaces that handle slices, care should be taken to define 40 reference ownership semantics (who should call unref?) and mutability 41 constraints (is the callee allowed to modify the slice?) */ 42 43 typedef struct grpc_slice_refcount_vtable { 44 void (*ref)(void*); 45 void (*unref)(void*); 46 int (*eq)(grpc_slice a, grpc_slice b); 47 uint32_t (*hash)(grpc_slice slice); 48 } grpc_slice_refcount_vtable; 49 50 /** Reference count container for grpc_slice. Contains function pointers to 51 increment and decrement reference counts. Implementations should cleanup 52 when the reference count drops to zero. 53 Typically client code should not touch this, and use grpc_slice_malloc, 54 grpc_slice_new, or grpc_slice_new_with_len instead. */ 55 typedef struct grpc_slice_refcount { 56 const grpc_slice_refcount_vtable* vtable; 57 /** If a subset of this slice is taken, use this pointer for the refcount. 58 Typically points back to the refcount itself, however iterning 59 implementations can use this to avoid a verification step on each hash 60 or equality check */ 61 struct grpc_slice_refcount* sub_refcount; 62 } grpc_slice_refcount; 63 64 /* Inlined half of grpc_slice is allowed to expand the size of the overall type 65 by this many bytes */ 66 #define GRPC_SLICE_INLINE_EXTRA_SIZE sizeof(void*) 67 68 #define GRPC_SLICE_INLINED_SIZE \ 69 (sizeof(size_t) + sizeof(uint8_t*) - 1 + GRPC_SLICE_INLINE_EXTRA_SIZE) 70 71 /** A grpc_slice s, if initialized, represents the byte range 72 s.bytes[0..s.length-1]. 73 74 It can have an associated ref count which has a destruction routine to be run 75 when the ref count reaches zero (see grpc_slice_new() and grp_slice_unref()). 76 Multiple grpc_slice values may share a ref count. 77 78 If the slice does not have a refcount, it represents an inlined small piece 79 of data that is copied by value. */ 80 struct grpc_slice { 81 struct grpc_slice_refcount* refcount; 82 union grpc_slice_data { 83 struct grpc_slice_refcounted { 84 uint8_t* bytes; 85 size_t length; 86 } refcounted; 87 struct grpc_slice_inlined { 88 uint8_t length; 89 uint8_t bytes[GRPC_SLICE_INLINED_SIZE]; 90 } inlined; 91 } data; 92 }; 93 94 #define GRPC_SLICE_BUFFER_INLINE_ELEMENTS 8 95 96 /** Represents an expandable array of slices, to be interpreted as a 97 single item. */ 98 typedef struct grpc_slice_buffer { 99 /** This is for internal use only. External users (i.e any code outside grpc 100 * core) MUST NOT use this field */ 101 grpc_slice* base_slices; 102 103 /** slices in the array (Points to the first valid grpc_slice in the array) */ 104 grpc_slice* slices; 105 /** the number of slices in the array */ 106 size_t count; 107 /** the number of slices allocated in the array. External users (i.e any code 108 * outside grpc core) MUST NOT use this field */ 109 size_t capacity; 110 /** the combined length of all slices in the array */ 111 size_t length; 112 /** inlined elements to avoid allocations */ 113 grpc_slice inlined[GRPC_SLICE_BUFFER_INLINE_ELEMENTS]; 114 } grpc_slice_buffer; 115 116 #define GRPC_SLICE_START_PTR(slice) \ 117 ((slice).refcount ? (slice).data.refcounted.bytes \ 118 : (slice).data.inlined.bytes) 119 #define GRPC_SLICE_LENGTH(slice) \ 120 ((slice).refcount ? (slice).data.refcounted.length \ 121 : (slice).data.inlined.length) 122 #define GRPC_SLICE_SET_LENGTH(slice, newlen) \ 123 ((slice).refcount ? ((slice).data.refcounted.length = (size_t)(newlen)) \ 124 : ((slice).data.inlined.length = (uint8_t)(newlen))) 125 #define GRPC_SLICE_END_PTR(slice) \ 126 GRPC_SLICE_START_PTR(slice) + GRPC_SLICE_LENGTH(slice) 127 #define GRPC_SLICE_IS_EMPTY(slice) (GRPC_SLICE_LENGTH(slice) == 0) 128 129 #ifdef GRPC_ALLOW_GPR_SLICE_FUNCTIONS 130 131 /* Duplicate GPR_* definitions */ 132 #define GPR_SLICE_START_PTR(slice) \ 133 ((slice).refcount ? (slice).data.refcounted.bytes \ 134 : (slice).data.inlined.bytes) 135 #define GPR_SLICE_LENGTH(slice) \ 136 ((slice).refcount ? (slice).data.refcounted.length \ 137 : (slice).data.inlined.length) 138 #define GPR_SLICE_SET_LENGTH(slice, newlen) \ 139 ((slice).refcount ? ((slice).data.refcounted.length = (size_t)(newlen)) \ 140 : ((slice).data.inlined.length = (uint8_t)(newlen))) 141 #define GPR_SLICE_END_PTR(slice) \ 142 GRPC_SLICE_START_PTR(slice) + GRPC_SLICE_LENGTH(slice) 143 #define GPR_SLICE_IS_EMPTY(slice) (GRPC_SLICE_LENGTH(slice) == 0) 144 145 #endif /* GRPC_ALLOW_GPR_SLICE_FUNCTIONS */ 146 147 #endif /* GRPC_IMPL_CODEGEN_SLICE_H */ 148