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 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. */ 81 GRPCAPI 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 */ 87 GRPCAPI int grpc_is_initialized(void); 88 89 /** EXPERIMENTAL. Blocking shut down grpc library. 90 This is only for wrapped language to use now. */ 91 GRPCAPI void grpc_shutdown_blocking(void); 92 93 /** Return a string representing the current version of grpc */ 94 GRPCAPI const char* grpc_version_string(void); 95 96 /** Return a string specifying what the 'g' in gRPC stands for */ 97 GRPCAPI 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 */ 101 GRPCAPI const grpc_completion_queue_factory* 102 grpc_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 */ 107 GRPCAPI 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 */ 112 GRPCAPI 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. */ 118 GRPCAPI 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 */ 123 GRPCAPI 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. */ 135 GRPCAPI 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. */ 150 GRPCAPI 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. */ 165 GRPCAPI 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 */ 169 GRPCAPI 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 */ 176 GRPCAPI 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 */ 185 GRPCAPI 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. */ 189 GRPCAPI 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. **/ 195 GRPCAPI 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. */ 203 GRPCAPI 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 */ 208 GRPCAPI 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). */ 217 GRPCAPI 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. */ 224 GRPCAPI 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 GRPCAPI void* grpc_channel_register_call(grpc_channel* channel, 229 const char* method, const char* host, 230 void* reserved); 231 232 /** Create a call given a handle returned from grpc_channel_register_call. 233 \sa grpc_channel_create_call. */ 234 GRPCAPI grpc_call* grpc_channel_create_registered_call( 235 grpc_channel* channel, grpc_call* parent_call, uint32_t propagation_mask, 236 grpc_completion_queue* completion_queue, void* registered_call_handle, 237 gpr_timespec deadline, void* reserved); 238 239 /** Allocate memory in the grpc_call arena: this memory is automatically 240 discarded at call completion */ 241 GRPCAPI void* grpc_call_arena_alloc(grpc_call* call, size_t size); 242 243 /** Start a batch of operations defined in the array ops; when complete, post a 244 completion of type 'tag' to the completion queue bound to the call. 245 The order of ops specified in the batch has no significance. 246 Only one operation of each type can be active at once in any given 247 batch. 248 If a call to grpc_call_start_batch returns GRPC_CALL_OK you must call 249 grpc_completion_queue_next or grpc_completion_queue_pluck on the completion 250 queue associated with 'call' for work to be performed. If a call to 251 grpc_call_start_batch returns any value other than GRPC_CALL_OK it is 252 guaranteed that no state associated with 'call' is changed and it is not 253 appropriate to call grpc_completion_queue_next or 254 grpc_completion_queue_pluck consequent to the failed grpc_call_start_batch 255 call. 256 If a call to grpc_call_start_batch with an empty batch returns 257 GRPC_CALL_OK, the tag is put in the completion queue immediately. 258 THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment 259 needs to be synchronized. As an optimization, you may synchronize batches 260 containing just send operations independently from batches containing just 261 receive operations. Access to grpc_call_start_batch with an empty batch is 262 thread-compatible. */ 263 GRPCAPI grpc_call_error grpc_call_start_batch(grpc_call* call, 264 const grpc_op* ops, size_t nops, 265 void* tag, void* reserved); 266 267 /** Returns a newly allocated string representing the endpoint to which this 268 call is communicating with. The string is in the uri format accepted by 269 grpc_channel_create. 270 The returned string should be disposed of with gpr_free(). 271 272 WARNING: this value is never authenticated or subject to any security 273 related code. It must not be used for any authentication related 274 functionality. Instead, use grpc_auth_context. */ 275 GRPCAPI char* grpc_call_get_peer(grpc_call* call); 276 277 struct census_context; 278 279 /** Set census context for a call; Must be called before first call to 280 grpc_call_start_batch(). */ 281 GRPCAPI void grpc_census_call_set_context(grpc_call* call, 282 struct census_context* context); 283 284 /** Retrieve the calls current census context. */ 285 GRPCAPI struct census_context* grpc_census_call_get_context(grpc_call* call); 286 287 /** Return a newly allocated string representing the target a channel was 288 created for. */ 289 GRPCAPI char* grpc_channel_get_target(grpc_channel* channel); 290 291 /** Request info about the channel. 292 \a channel_info indicates what information is being requested and 293 how that information will be returned. 294 \a channel_info is owned by the caller. */ 295 GRPCAPI void grpc_channel_get_info(grpc_channel* channel, 296 const grpc_channel_info* channel_info); 297 298 /** EXPERIMENTAL. Resets the channel's connect backoff. 299 TODO(roth): When we see whether this proves useful, either promote 300 to non-experimental or remove it. */ 301 GRPCAPI void grpc_channel_reset_connect_backoff(grpc_channel* channel); 302 303 /** Create a client channel to 'target'. Additional channel level configuration 304 MAY be provided by grpc_channel_args, though the expectation is that most 305 clients will want to simply pass NULL. The user data in 'args' need only 306 live through the invocation of this function. However, if any args of the 307 'pointer' type are passed, then the referenced vtable must be maintained 308 by the caller until grpc_channel_destroy terminates. See grpc_channel_args 309 definition for more on this. */ 310 GRPCAPI grpc_channel* grpc_insecure_channel_create( 311 const char* target, const grpc_channel_args* args, void* reserved); 312 313 /** Create a lame client: this client fails every operation attempted on it. */ 314 GRPCAPI grpc_channel* grpc_lame_client_channel_create( 315 const char* target, grpc_status_code error_code, const char* error_message); 316 317 /** Close and destroy a grpc channel */ 318 GRPCAPI void grpc_channel_destroy(grpc_channel* channel); 319 320 /** Error handling for grpc_call 321 Most grpc_call functions return a grpc_error. If the error is not GRPC_OK 322 then the operation failed due to some unsatisfied precondition. 323 If a grpc_call fails, it's guaranteed that no change to the call state 324 has been made. */ 325 326 /** Cancel an RPC. 327 Can be called multiple times, from any thread. 328 THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status 329 are thread-safe, and can be called at any point before grpc_call_unref 330 is called.*/ 331 GRPCAPI grpc_call_error grpc_call_cancel(grpc_call* call, void* reserved); 332 333 /** Cancel an RPC. 334 Can be called multiple times, from any thread. 335 If a status has not been received for the call, set it to the status code 336 and description passed in. 337 Importantly, this function does not send status nor description to the 338 remote endpoint. 339 Note that \a description doesn't need be a static string. 340 It doesn't need to be alive after the call to 341 grpc_call_cancel_with_status completes. 342 */ 343 GRPCAPI grpc_call_error grpc_call_cancel_with_status(grpc_call* call, 344 grpc_status_code status, 345 const char* description, 346 void* reserved); 347 348 /** Ref a call. 349 THREAD SAFETY: grpc_call_ref is thread-compatible */ 350 GRPCAPI void grpc_call_ref(grpc_call* call); 351 352 /** Unref a call. 353 THREAD SAFETY: grpc_call_unref is thread-compatible */ 354 GRPCAPI void grpc_call_unref(grpc_call* call); 355 356 /** Request notification of a new call. 357 Once a call is received, a notification tagged with \a tag_new is added to 358 \a cq_for_notification. \a call, \a details and \a request_metadata are 359 updated with the appropriate call information. \a cq_bound_to_call is bound 360 to \a call, and batch operation notifications for that call will be posted 361 to \a cq_bound_to_call. 362 Note that \a cq_for_notification must have been registered to the server via 363 \a grpc_server_register_completion_queue. */ 364 GRPCAPI grpc_call_error grpc_server_request_call( 365 grpc_server* server, grpc_call** call, grpc_call_details* details, 366 grpc_metadata_array* request_metadata, 367 grpc_completion_queue* cq_bound_to_call, 368 grpc_completion_queue* cq_for_notification, void* tag_new); 369 370 /** How to handle payloads for a registered method */ 371 typedef enum { 372 /** Don't try to read the payload */ 373 GRPC_SRM_PAYLOAD_NONE, 374 /** Read the initial payload as a byte buffer */ 375 GRPC_SRM_PAYLOAD_READ_INITIAL_BYTE_BUFFER 376 } grpc_server_register_method_payload_handling; 377 378 /** Registers a method in the server. 379 Methods to this (host, method) pair will not be reported by 380 grpc_server_request_call, but instead be reported by 381 grpc_server_request_registered_call when passed the appropriate 382 registered_method (as returned by this function). 383 Must be called before grpc_server_start. 384 Returns NULL on failure. */ 385 GRPCAPI void* grpc_server_register_method( 386 grpc_server* server, const char* method, const char* host, 387 grpc_server_register_method_payload_handling payload_handling, 388 uint32_t flags); 389 390 /** Request notification of a new pre-registered call. 'cq_for_notification' 391 must have been registered to the server via 392 grpc_server_register_completion_queue. */ 393 GRPCAPI grpc_call_error grpc_server_request_registered_call( 394 grpc_server* server, void* registered_method, grpc_call** call, 395 gpr_timespec* deadline, grpc_metadata_array* request_metadata, 396 grpc_byte_buffer** optional_payload, 397 grpc_completion_queue* cq_bound_to_call, 398 grpc_completion_queue* cq_for_notification, void* tag_new); 399 400 /** Create a server. Additional configuration for each incoming channel can 401 be specified with args. If no additional configuration is needed, args can 402 be NULL. The user data in 'args' need only live through the invocation of 403 this function. However, if any args of the 'pointer' type are passed, then 404 the referenced vtable must be maintained by the caller until 405 grpc_server_destroy terminates. See grpc_channel_args definition for more 406 on this. */ 407 GRPCAPI grpc_server* grpc_server_create(const grpc_channel_args* args, 408 void* reserved); 409 410 /** Register a completion queue with the server. Must be done for any 411 notification completion queue that is passed to grpc_server_request_*_call 412 and to grpc_server_shutdown_and_notify. Must be performed prior to 413 grpc_server_start. */ 414 GRPCAPI void grpc_server_register_completion_queue(grpc_server* server, 415 grpc_completion_queue* cq, 416 void* reserved); 417 418 /** Add a HTTP2 over plaintext over tcp listener. 419 Returns bound port number on success, 0 on failure. 420 REQUIRES: server not started */ 421 GRPCAPI int grpc_server_add_insecure_http2_port(grpc_server* server, 422 const char* addr); 423 424 /** Start a server - tells all listeners to start listening */ 425 GRPCAPI void grpc_server_start(grpc_server* server); 426 427 /** Begin shutting down a server. 428 After completion, no new calls or connections will be admitted. 429 Existing calls will be allowed to complete. 430 Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. 431 Shutdown is idempotent, and all tags will be notified at once if multiple 432 grpc_server_shutdown_and_notify calls are made. 'cq' must have been 433 registered to this server via grpc_server_register_completion_queue. */ 434 GRPCAPI void grpc_server_shutdown_and_notify(grpc_server* server, 435 grpc_completion_queue* cq, 436 void* tag); 437 438 /** Cancel all in-progress calls. 439 Only usable after shutdown. */ 440 GRPCAPI void grpc_server_cancel_all_calls(grpc_server* server); 441 442 /** Destroy a server. 443 Shutdown must have completed beforehand (i.e. all tags generated by 444 grpc_server_shutdown_and_notify must have been received, and at least 445 one call to grpc_server_shutdown_and_notify must have been made). */ 446 GRPCAPI void grpc_server_destroy(grpc_server* server); 447 448 /** Enable or disable a tracer. 449 450 Tracers (usually controlled by the environment variable GRPC_TRACE) 451 allow printf-style debugging on GRPC internals, and are useful for 452 tracking down problems in the field. 453 454 Use of this function is not strictly thread-safe, but the 455 thread-safety issues raised by it should not be of concern. */ 456 GRPCAPI int grpc_tracer_set_enabled(const char* name, int enabled); 457 458 /** Check whether a metadata key is legal (will be accepted by core) */ 459 GRPCAPI int grpc_header_key_is_legal(grpc_slice slice); 460 461 /** Check whether a non-binary metadata value is legal (will be accepted by 462 core) */ 463 GRPCAPI int grpc_header_nonbin_value_is_legal(grpc_slice slice); 464 465 /** Check whether a metadata key corresponds to a binary value */ 466 GRPCAPI int grpc_is_binary_header(grpc_slice slice); 467 468 /** Convert grpc_call_error values to a string */ 469 GRPCAPI const char* grpc_call_error_to_string(grpc_call_error error); 470 471 /** Create a buffer pool */ 472 GRPCAPI grpc_resource_quota* grpc_resource_quota_create(const char* trace_name); 473 474 /** Add a reference to a buffer pool */ 475 GRPCAPI void grpc_resource_quota_ref(grpc_resource_quota* resource_quota); 476 477 /** Drop a reference to a buffer pool */ 478 GRPCAPI void grpc_resource_quota_unref(grpc_resource_quota* resource_quota); 479 480 /** Update the size of a buffer pool */ 481 GRPCAPI void grpc_resource_quota_resize(grpc_resource_quota* resource_quota, 482 size_t new_size); 483 484 /** Update the size of the maximum number of threads allowed */ 485 GRPCAPI void grpc_resource_quota_set_max_threads( 486 grpc_resource_quota* resource_quota, int new_max_threads); 487 488 /** Fetch a vtable for a grpc_channel_arg that points to a grpc_resource_quota 489 */ 490 GRPCAPI const grpc_arg_pointer_vtable* grpc_resource_quota_arg_vtable(void); 491 492 /************* CHANNELZ API *************/ 493 /** Channelz is under active development. The following APIs will see some 494 churn as the feature is implemented. This comment will be removed once 495 channelz is officially supported, and these APIs become stable. For now 496 you may track the progress by following this github issue: 497 https://github.com/grpc/grpc/issues/15340 498 499 the following APIs return allocated JSON strings that match the response 500 objects from the channelz proto, found here: 501 https://github.com/grpc/grpc/blob/master/src/proto/grpc/channelz/channelz.proto. 502 503 For easy conversion to protobuf, The JSON is formatted according to: 504 https://developers.google.com/protocol-buffers/docs/proto3#json. */ 505 506 /* Gets all root channels (i.e. channels the application has directly 507 created). This does not include subchannels nor non-top level channels. 508 The returned string is allocated and must be freed by the application. */ 509 GRPCAPI char* grpc_channelz_get_top_channels(intptr_t start_channel_id); 510 511 /* Gets all servers that exist in the process. */ 512 GRPCAPI char* grpc_channelz_get_servers(intptr_t start_server_id); 513 514 /* Returns a single Server, or else a NOT_FOUND code. */ 515 GRPCAPI char* grpc_channelz_get_server(intptr_t server_id); 516 517 /* Gets all server sockets that exist in the server. */ 518 GRPCAPI char* grpc_channelz_get_server_sockets(intptr_t server_id, 519 intptr_t start_socket_id, 520 intptr_t max_results); 521 522 /* Returns a single Channel, or else a NOT_FOUND code. The returned string 523 is allocated and must be freed by the application. */ 524 GRPCAPI char* grpc_channelz_get_channel(intptr_t channel_id); 525 526 /* Returns a single Subchannel, or else a NOT_FOUND code. The returned string 527 is allocated and must be freed by the application. */ 528 GRPCAPI char* grpc_channelz_get_subchannel(intptr_t subchannel_id); 529 530 /* Returns a single Socket, or else a NOT_FOUND code. The returned string 531 is allocated and must be freed by the application. */ 532 GRPCAPI char* grpc_channelz_get_socket(intptr_t socket_id); 533 534 #ifdef __cplusplus 535 } 536 #endif 537 538 #endif /* GRPC_GRPC_H */ 539