• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  *
3  * Copyright 2015-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_GRPC_H
20 #define GRPC_GRPC_H
21 
22 #include <grpc/support/port_platform.h>
23 
24 #include <grpc/status.h>
25 
26 #include <grpc/byte_buffer.h>
27 #include <grpc/impl/codegen/connectivity_state.h>
28 #include <grpc/impl/codegen/grpc_types.h>
29 #include <grpc/impl/codegen/propagation_bits.h>
30 #include <grpc/slice.h>
31 #include <grpc/support/time.h>
32 #include <stddef.h>
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 /*! \mainpage GRPC Core
39  *
40  * The GRPC Core library is a low-level library designed to be wrapped by higher
41  * level libraries. The top-level API is provided in grpc.h. Security related
42  * functionality lives in grpc_security.h.
43  */
44 
45 GRPCAPI void grpc_metadata_array_init(grpc_metadata_array* array);
46 GRPCAPI void grpc_metadata_array_destroy(grpc_metadata_array* array);
47 
48 GRPCAPI void grpc_call_details_init(grpc_call_details* details);
49 GRPCAPI void grpc_call_details_destroy(grpc_call_details* details);
50 
51 /** Registers a plugin to be initialized and destroyed with the library.
52 
53     The \a init and \a destroy functions will be invoked as part of
54     \a grpc_init() and \a grpc_shutdown(), respectively.
55     Note that these functions can be invoked an arbitrary number of times
56     (and hence so will \a init and \a destroy).
57     It is safe to pass NULL to either argument. Plugins are destroyed in
58     the reverse order they were initialized. */
59 GRPCAPI void grpc_register_plugin(void (*init)(void), void (*destroy)(void));
60 
61 /** Initialize the grpc library.
62 
63     After it's called, a matching invocation to grpc_shutdown() is expected.
64 
65     It is not safe to call any other grpc functions before calling this.
66     (To avoid overhead, little checking is done, and some things may work. We
67     do not warrant that they will continue to do so in future revisions of this
68     library). */
69 GRPCAPI void grpc_init(void);
70 
71 /** Shut down the grpc library.
72 
73     Before it's called, there should haven been a matching invocation to
74     grpc_init().
75 
76     No memory is used by grpc after this call returns, nor are any instructions
77     executing within the grpc library.
78     Prior to calling, all application owned grpc objects must have been
79     destroyed. */
80 GRPCAPI void grpc_shutdown(void);
81 
82 /** EXPERIMENTAL. Returns 1 if the grpc library has been initialized.
83     TODO(ericgribkoff) Decide if this should be promoted to non-experimental as
84     part of stabilizing the fork support API, as tracked in
85     https://github.com/grpc/grpc/issues/15334 */
86 GRPCAPI int grpc_is_initialized(void);
87 
88 /** Return a string representing the current version of grpc */
89 GRPCAPI const char* grpc_version_string(void);
90 
91 /** Return a string specifying what the 'g' in gRPC stands for */
92 GRPCAPI const char* grpc_g_stands_for(void);
93 
94 /** Returns the completion queue factory based on the attributes. MAY return a
95     NULL if no factory can be found */
96 GRPCAPI const grpc_completion_queue_factory*
97 grpc_completion_queue_factory_lookup(
98     const grpc_completion_queue_attributes* attributes);
99 
100 /** Helper function to create a completion queue with grpc_cq_completion_type
101     of GRPC_CQ_NEXT and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING */
102 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_next(
103     void* reserved);
104 
105 /** Helper function to create a completion queue with grpc_cq_completion_type
106     of GRPC_CQ_PLUCK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING */
107 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_pluck(
108     void* reserved);
109 
110 /** Helper function to create a completion queue with grpc_cq_completion_type
111     of GRPC_CQ_CALLBACK and grpc_cq_polling_type of GRPC_CQ_DEFAULT_POLLING.
112     This function is experimental. */
113 GRPCAPI grpc_completion_queue* grpc_completion_queue_create_for_callback(
114     grpc_experimental_completion_queue_functor* shutdown_callback,
115     void* reserved);
116 
117 /** Create a completion queue */
118 GRPCAPI grpc_completion_queue* grpc_completion_queue_create(
119     const grpc_completion_queue_factory* factory,
120     const grpc_completion_queue_attributes* attributes, void* reserved);
121 
122 /** Blocks until an event is available, the completion queue is being shut down,
123     or deadline is reached.
124 
125     Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout,
126     otherwise a grpc_event describing the event that occurred.
127 
128     Callers must not call grpc_completion_queue_next and
129     grpc_completion_queue_pluck simultaneously on the same completion queue. */
130 GRPCAPI grpc_event grpc_completion_queue_next(grpc_completion_queue* cq,
131                                               gpr_timespec deadline,
132                                               void* reserved);
133 
134 /** Blocks until an event with tag 'tag' is available, the completion queue is
135     being shutdown or deadline is reached.
136 
137     Returns a grpc_event with type GRPC_QUEUE_TIMEOUT on timeout,
138     otherwise a grpc_event describing the event that occurred.
139 
140     Callers must not call grpc_completion_queue_next and
141     grpc_completion_queue_pluck simultaneously on the same completion queue.
142 
143     Completion queues support a maximum of GRPC_MAX_COMPLETION_QUEUE_PLUCKERS
144     concurrently executing plucks at any time. */
145 GRPCAPI grpc_event grpc_completion_queue_pluck(grpc_completion_queue* cq,
146                                                void* tag, gpr_timespec deadline,
147                                                void* reserved);
148 
149 /** Maximum number of outstanding grpc_completion_queue_pluck executions per
150     completion queue */
151 #define GRPC_MAX_COMPLETION_QUEUE_PLUCKERS 6
152 
153 /** Begin destruction of a completion queue. Once all possible events are
154     drained then grpc_completion_queue_next will start to produce
155     GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call
156     grpc_completion_queue_destroy.
157 
158     After calling this function applications should ensure that no
159     NEW work is added to be published on this completion queue. */
160 GRPCAPI void grpc_completion_queue_shutdown(grpc_completion_queue* cq);
161 
162 /** Destroy a completion queue. The caller must ensure that the queue is
163     drained and no threads are executing grpc_completion_queue_next */
164 GRPCAPI void grpc_completion_queue_destroy(grpc_completion_queue* cq);
165 
166 /*********** EXPERIMENTAL API ************/
167 /** Initializes a thread local cache for \a cq.
168  * grpc_flush_cq_tls_cache() MUST be called on the same thread,
169  * with the same cq.
170  */
171 GRPCAPI void grpc_completion_queue_thread_local_cache_init(
172     grpc_completion_queue* cq);
173 
174 /*********** EXPERIMENTAL API ************/
175 /** Flushes the thread local cache for \a cq.
176  * Returns 1 if there was contents in the cache.  If there was an event
177  * in \a cq tls cache, its tag is placed in tag, and ok is set to the
178  * event success.
179  */
180 GRPCAPI int grpc_completion_queue_thread_local_cache_flush(
181     grpc_completion_queue* cq, void** tag, int* ok);
182 
183 /** Check the connectivity state of a channel. */
184 GRPCAPI grpc_connectivity_state grpc_channel_check_connectivity_state(
185     grpc_channel* channel, int try_to_connect);
186 
187 /** Number of active "external connectivity state watchers" attached to a
188  * channel.
189  * Useful for testing. **/
190 GRPCAPI int grpc_channel_num_external_connectivity_watchers(
191     grpc_channel* channel);
192 
193 /** Watch for a change in connectivity state.
194     Once the channel connectivity state is different from last_observed_state,
195     tag will be enqueued on cq with success=1.
196     If deadline expires BEFORE the state is changed, tag will be enqueued on cq
197     with success=0. */
198 GRPCAPI void grpc_channel_watch_connectivity_state(
199     grpc_channel* channel, grpc_connectivity_state last_observed_state,
200     gpr_timespec deadline, grpc_completion_queue* cq, void* tag);
201 
202 /** Check whether a grpc channel supports connectivity watcher */
203 GRPCAPI int grpc_channel_support_connectivity_watcher(grpc_channel* channel);
204 
205 /** Create a call given a grpc_channel, in order to call 'method'. All
206     completions are sent to 'completion_queue'. 'method' and 'host' need only
207     live through the invocation of this function.
208     If parent_call is non-NULL, it must be a server-side call. It will be used
209     to propagate properties from the server call to this new client call,
210     depending on the value of \a propagation_mask (see propagation_bits.h for
211     possible values). */
212 GRPCAPI grpc_call* grpc_channel_create_call(
213     grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
214     grpc_completion_queue* completion_queue, grpc_slice method,
215     const grpc_slice* host, gpr_timespec deadline, void* reserved);
216 
217 /** Ping the channels peer (load balanced channels will select one sub-channel
218     to ping); if the channel is not connected, posts a failed. */
219 GRPCAPI void grpc_channel_ping(grpc_channel* channel, grpc_completion_queue* cq,
220                                void* tag, void* reserved);
221 
222 /** Pre-register a method/host pair on a channel. */
223 GRPCAPI void* grpc_channel_register_call(grpc_channel* channel,
224                                          const char* method, const char* host,
225                                          void* reserved);
226 
227 /** Create a call given a handle returned from grpc_channel_register_call.
228     \sa grpc_channel_create_call. */
229 GRPCAPI grpc_call* grpc_channel_create_registered_call(
230     grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask,
231     grpc_completion_queue* completion_queue, void* registered_call_handle,
232     gpr_timespec deadline, void* reserved);
233 
234 /** Allocate memory in the grpc_call arena: this memory is automatically
235     discarded at call completion */
236 GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size);
237 
238 /** Start a batch of operations defined in the array ops; when complete, post a
239     completion of type 'tag' to the completion queue bound to the call.
240     The order of ops specified in the batch has no significance.
241     Only one operation of each type can be active at once in any given
242     batch.
243     If a call to grpc_call_start_batch returns GRPC_CALL_OK you must call
244     grpc_completion_queue_next or grpc_completion_queue_pluck on the completion
245     queue associated with 'call' for work to be performed. If a call to
246     grpc_call_start_batch returns any value other than GRPC_CALL_OK it is
247     guaranteed that no state associated with 'call' is changed and it is not
248     appropriate to call grpc_completion_queue_next or
249     grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch
250     call.
251     THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment
252     needs to be synchronized. As an optimization, you may synchronize batches
253     containing just send operations independently from batches containing just
254     receive operations. */
255 GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call* call,
256                                               const grpc_op* ops, size_t nops,
257                                               void* tag, void* reserved);
258 
259 /** Returns a newly allocated string representing the endpoint to which this
260     call is communicating with. The string is in the uri format accepted by
261     grpc_channel_create.
262     The returned string should be disposed of with gpr_free().
263 
264     WARNING: this value is never authenticated or subject to any security
265     related code. It must not be used for any authentication related
266     functionality. Instead, use grpc_auth_context. */
267 GRPCAPI char* grpc_call_get_peer(grpc_call* call);
268 
269 struct census_context;
270 
271 /** Set census context for a call; Must be called before first call to
272    grpc_call_start_batch(). */
273 GRPCAPI void grpc_census_call_set_context(grpc_call* call,
274                                           struct census_context* context);
275 
276 /** Retrieve the calls current census context. */
277 GRPCAPI struct census_context* grpc_census_call_get_context(grpc_call* call);
278 
279 /** Return a newly allocated string representing the target a channel was
280     created for. */
281 GRPCAPI char* grpc_channel_get_target(grpc_channel* channel);
282 
283 /** Request info about the channel.
284     \a channel_info indicates what information is being requested and
285     how that information will be returned.
286     \a channel_info is owned by the caller. */
287 GRPCAPI void grpc_channel_get_info(grpc_channel* channel,
288                                    const grpc_channel_info* channel_info);
289 
290 /** EXPERIMENTAL.  Resets the channel's connect backoff.
291     TODO(roth): When we see whether this proves useful, either promote
292     to non-experimental or remove it. */
293 GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel* channel);
294 
295 /** Create a client channel to 'target'. Additional channel level configuration
296     MAY be provided by grpc_channel_args, though the expectation is that most
297     clients will want to simply pass NULL. The user data in 'args' need only
298     live through the invocation of this function. However, if any args of the
299     'pointer' type are passed, then the referenced vtable must be maintained
300     by the caller until grpc_channel_destroy terminates. See grpc_channel_args
301     definition for more on this. */
302 GRPCAPI grpc_channel* grpc_insecure_channel_create(
303     const char* target, const grpc_channel_args* args, void* reserved);
304 
305 /** Create a lame client: this client fails every operation attempted on it. */
306 GRPCAPI grpc_channel* grpc_lame_client_channel_create(
307     const char* target, grpc_status_code error_code, const char* error_message);
308 
309 /** Close and destroy a grpc channel */
310 GRPCAPI void grpc_channel_destroy(grpc_channel* channel);
311 
312 /** Error handling for grpc_call
313    Most grpc_call functions return a grpc_error. If the error is not GRPC_OK
314    then the operation failed due to some unsatisfied precondition.
315    If a grpc_call fails, it's guaranteed that no change to the call state
316    has been made. */
317 
318 /** Called by clients to cancel an RPC on the server.
319     Can be called multiple times, from any thread.
320     THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status
321     are thread-safe, and can be called at any point before grpc_call_unref
322     is called.*/
323 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved);
324 
325 /** Called by clients to cancel an RPC on the server.
326     Can be called multiple times, from any thread.
327     If a status has not been received for the call, set it to the status code
328     and description passed in.
329     Importantly, this function does not send status nor description to the
330     remote endpoint.
331     Note that \a description doesn't need be a static string.
332     It doesn't need to be alive after the call to
333     grpc_call_cancel_with_status completes.
334     */
335 GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call* call,
336                                                      grpc_status_code status,
337                                                      const char* description,
338                                                      void* reserved);
339 
340 /** Ref a call.
341     THREAD SAFETY: grpc_call_ref is thread-compatible */
342 GRPCAPI void grpc_call_ref(grpc_call* call);
343 
344 /** Unref a call.
345     THREAD SAFETY: grpc_call_unref is thread-compatible */
346 GRPCAPI void grpc_call_unref(grpc_call* call);
347 
348 /** Request notification of a new call.
349     Once a call is received, a notification tagged with \a tag_new is added to
350     \a cq_for_notification. \a call, \a details and \a request_metadata are
351     updated with the appropriate call information. \a cq_bound_to_call is bound
352     to \a call, and batch operation notifications for that call will be posted
353     to \a cq_bound_to_call.
354     Note that \a cq_for_notification must have been registered to the server via
355     \a grpc_server_register_completion_queue. */
356 GRPCAPI grpc_call_error grpc_server_request_call(
357     grpc_server* server, grpc_call** call, grpc_call_details* details,
358     grpc_metadata_array* request_metadata,
359     grpc_completion_queue* cq_bound_to_call,
360     grpc_completion_queue* cq_for_notification, void* tag_new);
361 
362 /** How to handle payloads for a registered method */
363 typedef enum {
364   /** Don't try to read the payload */
365   GRPC_SRM_PAYLOAD_NONE,
366   /** Read the initial payload as a byte buffer */
367   GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER
368 } grpc_server_register_method_payload_handling;
369 
370 /** Registers a method in the server.
371     Methods to this (host, method) pair will not be reported by
372     grpc_server_request_call, but instead be reported by
373     grpc_server_request_registered_call when passed the appropriate
374     registered_method (as returned by this function).
375     Must be called before grpc_server_start.
376     Returns NULL on failure. */
377 GRPCAPI void* grpc_server_register_method(
378     grpc_server* server, const char* method, const char* host,
379     grpc_server_register_method_payload_handling payload_handling,
380     uint32_t flags);
381 
382 /** Request notification of a new pre-registered call. 'cq_for_notification'
383     must have been registered to the server via
384     grpc_server_register_completion_queue. */
385 GRPCAPI grpc_call_error grpc_server_request_registered_call(
386     grpc_server* server, void* registered_method, grpc_call** call,
387     gpr_timespec* deadline, grpc_metadata_array* request_metadata,
388     grpc_byte_buffer** optional_payload,
389     grpc_completion_queue* cq_bound_to_call,
390     grpc_completion_queue* cq_for_notification, void* tag_new);
391 
392 /** Create a server. Additional configuration for each incoming channel can
393     be specified with args. If no additional configuration is needed, args can
394     be NULL. The user data in 'args' need only live through the invocation of
395     this function. However, if any args of the 'pointer' type are passed, then
396     the referenced vtable must be maintained by the caller until
397     grpc_server_destroy terminates. See grpc_channel_args definition for more
398     on this. */
399 GRPCAPI grpc_server* grpc_server_create(const grpc_channel_args* args,
400                                         void* reserved);
401 
402 /** Register a completion queue with the server. Must be done for any
403     notification completion queue that is passed to grpc_server_request_*_call
404     and to grpc_server_shutdown_and_notify. Must be performed prior to
405     grpc_server_start. */
406 GRPCAPI void grpc_server_register_completion_queue(grpc_server* server,
407                                                    grpc_completion_queue* cq,
408                                                    void* reserved);
409 
410 /** Add a HTTP2 over plaintext over tcp listener.
411     Returns bound port number on success, 0 on failure.
412     REQUIRES: server not started */
413 GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server* server,
414                                                 const char* addr);
415 
416 /** Start a server - tells all listeners to start listening */
417 GRPCAPI void grpc_server_start(grpc_server* server);
418 
419 /** Begin shutting down a server.
420     After completion, no new calls or connections will be admitted.
421     Existing calls will be allowed to complete.
422     Send a GRPC_OP_COMPLETE event when there are no more calls being serviced.
423     Shutdown is idempotent, and all tags will be notified at once if multiple
424     grpc_server_shutdown_and_notify calls are made. 'cq' must have been
425     registered to this server via grpc_server_register_completion_queue. */
426 GRPCAPI void grpc_server_shutdown_and_notify(grpc_server* server,
427                                              grpc_completion_queue* cq,
428                                              void* tag);
429 
430 /** Cancel all in-progress calls.
431     Only usable after shutdown. */
432 GRPCAPI void grpc_server_cancel_all_calls(grpc_server* server);
433 
434 /** Destroy a server.
435     Shutdown must have completed beforehand (i.e. all tags generated by
436     grpc_server_shutdown_and_notify must have been received, and at least
437     one call to grpc_server_shutdown_and_notify must have been made). */
438 GRPCAPI void grpc_server_destroy(grpc_server* server);
439 
440 /** Enable or disable a tracer.
441 
442     Tracers (usually controlled by the environment variable GRPC_TRACE)
443     allow printf-style debugging on GRPC internals, and are useful for
444     tracking down problems in the field.
445 
446     Use of this function is not strictly thread-safe, but the
447     thread-safety issues raised by it should not be of concern. */
448 GRPCAPI int grpc_tracer_set_enabled(const char* name, int enabled);
449 
450 /** Check whether a metadata key is legal (will be accepted by core) */
451 GRPCAPI int grpc_header_key_is_legal(grpc_slice slice);
452 
453 /** Check whether a non-binary metadata value is legal (will be accepted by
454     core) */
455 GRPCAPI int grpc_header_nonbin_value_is_legal(grpc_slice slice);
456 
457 /** Check whether a metadata key corresponds to a binary value */
458 GRPCAPI int grpc_is_binary_header(grpc_slice slice);
459 
460 /** Convert grpc_call_error values to a string */
461 GRPCAPI const char* grpc_call_error_to_string(grpc_call_error error);
462 
463 /** Create a buffer pool */
464 GRPCAPI grpc_resource_quota* grpc_resource_quota_create(const char* trace_name);
465 
466 /** Add a reference to a buffer pool */
467 GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota* resource_quota);
468 
469 /** Drop a reference to a buffer pool */
470 GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota* resource_quota);
471 
472 /** Update the size of a buffer pool */
473 GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota* resource_quota,
474                                         size_t new_size);
475 
476 /** Update the size of the maximum number of threads allowed */
477 GRPCAPI void grpc_resource_quota_set_max_threads(
478     grpc_resource_quota* resource_quota, int new_max_threads);
479 
480 /** Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota
481  */
482 GRPCAPI const grpc_arg_pointer_vtable* grpc_resource_quota_arg_vtable(void);
483 
484 /************* CHANNELZ API *************/
485 /** Channelz is under active development. The following APIs will see some
486     churn as the feature is implemented. This comment will be removed once
487     channelz is officially supported, and these APIs become stable. For now
488     you may track the progress by following this github issue:
489     https://github.com/grpc/grpc/issues/15340
490 
491     the following APIs return allocated JSON strings that match the response
492     objects from the channelz proto, found here:
493     https://github.com/grpc/grpc/blob/master/src/proto/grpc/channelz/channelz.proto.
494 
495     For easy conversion to protobuf, The JSON is formatted according to:
496     https://developers.google.com/protocol-buffers/docs/proto3#json. */
497 
498 /* Gets all root channels (i.e. channels the application has directly
499    created). This does not include subchannels nor non-top level channels.
500    The returned string is allocated and must be freed by the application. */
501 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id);
502 
503 /* Gets all servers that exist in the process. */
504 GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id);
505 
506 /* Returns a single Channel, or else a NOT_FOUND code. The returned string
507    is allocated and must be freed by the application. */
508 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id);
509 
510 /* Returns a single Subchannel, or else a NOT_FOUND code. The returned string
511    is allocated and must be freed by the application. */
512 GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id);
513 
514 #ifdef __cplusplus
515 }
516 #endif
517 
518 #endif /* GRPC_GRPC_H */
519