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

source code of include/grpc/grpc.h