GRPC Core  18.0.0
resource_quota.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright 2016 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_CORE_LIB_IOMGR_RESOURCE_QUOTA_H
20 #define GRPC_CORE_LIB_IOMGR_RESOURCE_QUOTA_H
21 
23 
24 #include <grpc/grpc.h>
25 
28 
67 
68 // TODO(juanlishen): This is a hack. We need to do real accounting instead of
69 // hard coding.
70 constexpr size_t GRPC_RESOURCE_QUOTA_CALL_SIZE = 15 * 1024;
71 constexpr size_t GRPC_RESOURCE_QUOTA_CHANNEL_SIZE = 50 * 1024;
72 
74  grpc_resource_quota* resource_quota);
77  const grpc_channel_args* channel_args, bool create = true);
78 
79 /* Return a number indicating current memory pressure:
80  0.0 ==> no memory usage
81  1.0 ==> maximum memory usage */
83  grpc_resource_quota* resource_quota);
84 
86 
88 
91 
92 /* Returns a borrowed reference to the underlying resource quota for this
93  resource user. */
95  grpc_resource_user* resource_user);
96 
97 void grpc_resource_user_ref(grpc_resource_user* resource_user);
98 void grpc_resource_user_unref(grpc_resource_user* resource_user);
100 
101 /* Attempts to get quota from the resource_user to create 'thread_count' number
102  * of threads. Returns true if successful (i.e the caller is now free to create
103  * 'thread_count' number of threads) or false if quota is not available */
105  int thread_count);
106 /* Releases 'thread_count' worth of quota back to the resource user. The quota
107  * should have been previously obtained successfully by calling
108  * grpc_resource_user_allocate_threads().
109  *
110  * Note: There need not be an exact one-to-one correspondence between
111  * grpc_resource_user_allocate_threads() and grpc_resource_user_free_threads()
112  * calls. The only requirement is that the number of threads allocated should
113  * all be eventually released */
115  int thread_count);
116 
117 /* Allocates from the resource user 'size' worth of memory if this won't exceed
118  * the resource quota's total size. Returns whether the allocation is done
119  * successfully. If allocated successfully, the memory should be freed by the
120  * caller eventually. */
122  size_t size);
123 /* Allocates from the resource user 'size' worth of memory.
124  * If optional_on_done is NULL, then allocate immediately. This may push the
125  * quota over-limit, at which point reclamation will kick in. The caller is
126  * always responsible to free the memory eventually.
127  * Returns true if the allocation was successful. Otherwise, if optional_on_done
128  * is non-NULL, it will be scheduled without error when the allocation has been
129  * granted by the quota, and the caller is responsible to free the memory
130  * eventually. Or it may be scheduled with an error, in which case the caller
131  * fails to allocate the memory and shouldn't free the memory.
132  */
133 bool grpc_resource_user_alloc(grpc_resource_user* resource_user, size_t size,
134  grpc_closure* optional_on_done)
136 /* Release memory back to the quota */
137 void grpc_resource_user_free(grpc_resource_user* resource_user, size_t size);
138 /* Post a memory reclaimer to the resource user. Only one benign and one
139  destructive reclaimer can be posted at once. When executed, the reclaimer
140  MUST call grpc_resource_user_finish_reclamation before it completes, to
141  return control to the resource quota. */
143  bool destructive, grpc_closure* closure);
144 /* Finish a reclamation step */
146 
147 /* Helper to allocate slices from a resource user */
149  /* Closure for when a resource user allocation completes */
151  /* Closure to call when slices have been allocated */
153  /* Length of slices to allocate on the current request */
154  size_t length;
155  /* Number of slices to allocate on the current request */
156  size_t count;
157  /* Destination for slices to allocate on the current request */
159  /* Parent resource user */
162 
163 /* Initialize a slice allocator.
164  When an allocation is completed, calls \a cb with arg \p. */
166  grpc_resource_user_slice_allocator* slice_allocator,
167  grpc_resource_user* resource_user, grpc_iomgr_cb_func cb, void* p);
168 
169 /* Allocate \a count slices of length \a length into \a dest. Only one request
170  can be outstanding at a time.
171  Returns whether the slice was allocated inline in the function. If true,
172  the \a slice_allocator->on_allocated callback will not be called. */
174  grpc_resource_user_slice_allocator* slice_allocator, size_t length,
175  size_t count, grpc_slice_buffer* dest) GRPC_MUST_USE_RESULT;
176 
177 #endif /* GRPC_CORE_LIB_IOMGR_RESOURCE_QUOTA_H */
Definition: trace.h:61
void(* grpc_iomgr_cb_func)(void *arg, grpc_error_handle error)
gRPC Callback definition.
Definition: closure.h:53
#define GRPC_MUST_USE_RESULT
Definition: port_platform.h:524
bool grpc_resource_user_safe_alloc(grpc_resource_user *resource_user, size_t size)
Definition: resource_quota.cc:912
grpc_resource_quota * grpc_resource_quota_from_channel_args(const grpc_channel_args *channel_args, bool create=true)
Definition: resource_quota.cc:741
void grpc_resource_user_post_reclaimer(grpc_resource_user *resource_user, bool destructive, grpc_closure *closure)
Definition: resource_quota.cc:969
bool grpc_resource_user_alloc(grpc_resource_user *resource_user, size_t size, grpc_closure *optional_on_done) GRPC_MUST_USE_RESULT
Definition: resource_quota.cc:933
size_t grpc_resource_quota_peek_size(grpc_resource_quota *resource_quota)
Definition: resource_quota.cc:732
grpc_core::TraceFlag grpc_resource_quota_trace
void grpc_resource_user_free(grpc_resource_user *resource_user, size_t size)
Definition: resource_quota.cc:946
void grpc_resource_user_shutdown(grpc_resource_user *resource_user)
Definition: resource_quota.cc:845
grpc_resource_user * grpc_resource_user_create(grpc_resource_quota *resource_quota, const char *name)
Definition: resource_quota.cc:777
void grpc_resource_user_unref(grpc_resource_user *resource_user)
Definition: resource_quota.cc:841
void grpc_resource_user_ref(grpc_resource_user *resource_user)
Definition: resource_quota.cc:837
double grpc_resource_quota_get_memory_pressure(grpc_resource_quota *resource_quota)
Definition: resource_quota.cc:703
bool grpc_resource_user_alloc_slices(grpc_resource_user_slice_allocator *slice_allocator, size_t length, size_t count, grpc_slice_buffer *dest) GRPC_MUST_USE_RESULT
Definition: resource_quota.cc:999
grpc_resource_quota * grpc_resource_user_quota(grpc_resource_user *resource_user)
Definition: resource_quota.cc:817
void grpc_resource_quota_unref_internal(grpc_resource_quota *resource_quota)
Definition: resource_quota.cc:676
bool grpc_resource_user_allocate_threads(grpc_resource_user *resource_user, int thread_count)
Definition: resource_quota.cc:853
void grpc_resource_user_slice_allocator_init(grpc_resource_user_slice_allocator *slice_allocator, grpc_resource_user *resource_user, grpc_iomgr_cb_func cb, void *p)
Definition: resource_quota.cc:989
void grpc_resource_user_finish_reclamation(grpc_resource_user *resource_user)
Definition: resource_quota.cc:978
grpc_resource_quota * grpc_resource_quota_ref_internal(grpc_resource_quota *resource_quota)
Definition: resource_quota.cc:692
void grpc_resource_user_free_threads(grpc_resource_user *resource_user, int thread_count)
Definition: resource_quota.cc:869
constexpr size_t GRPC_RESOURCE_QUOTA_CHANNEL_SIZE
Definition: resource_quota.h:71
constexpr size_t GRPC_RESOURCE_QUOTA_CALL_SIZE
Definition: resource_quota.h:70
struct grpc_resource_user_slice_allocator grpc_resource_user_slice_allocator
grpc_closure closure
Definition: server.cc:460
An array of arguments that can be passed around.
Definition: grpc_types.h:132
A closure over a grpc_iomgr_cb_func.
Definition: closure.h:56
Definition: resource_quota.cc:127
Definition: resource_quota.h:148
grpc_slice_buffer * dest
Definition: resource_quota.h:158
grpc_resource_user * resource_user
Definition: resource_quota.h:160
grpc_closure on_done
Definition: resource_quota.h:152
size_t length
Definition: resource_quota.h:154
grpc_closure on_allocated
Definition: resource_quota.h:150
size_t count
Definition: resource_quota.h:156
Definition: resource_quota.cc:65
grpc_resource_quota * resource_quota
Definition: resource_quota.cc:67
std::string name
Definition: resource_quota.cc:124
Represents an expandable array of slices, to be interpreted as a single item.
Definition: slice.h:78