include/grpc/slice.h

   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 occurrence 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 */