diff options
Diffstat (limited to 'include')
| -rw-r--r-- | include/grpc++/channel_arguments.h | 4 | ||||
| -rw-r--r-- | include/grpc++/client_context.h | 9 | ||||
| -rw-r--r-- | include/grpc++/completion_queue.h | 3 | ||||
| -rw-r--r-- | include/grpc++/fixed_size_thread_pool.h | 8 | ||||
| -rw-r--r-- | include/grpc++/server_context.h | 14 | ||||
| -rw-r--r-- | include/grpc++/thread_pool_interface.h | 2 | ||||
| -rw-r--r-- | include/grpc/compression.h | 31 | ||||
| -rw-r--r-- | include/grpc/grpc.h | 388 | ||||
| -rw-r--r-- | include/grpc/support/time.h | 42 |
9 files changed, 280 insertions, 221 deletions
diff --git a/include/grpc++/channel_arguments.h b/include/grpc++/channel_arguments.h index 68f24cde4a..d726b9ffea 100644 --- a/include/grpc++/channel_arguments.h +++ b/include/grpc++/channel_arguments.h @@ -59,8 +59,8 @@ class ChannelArguments { void SetSslTargetNameOverride(const grpc::string& name); // TODO(yangg) add flow control options - // Set the compression level for the channel. - void SetCompressionLevel(grpc_compression_level level); + // Set the compression algorithm for the channel. + void SetCompressionAlgorithm(grpc_compression_algorithm algorithm); // Generic channel argument setters. Only for advanced use cases. void SetInt(const grpc::string& key, int value); diff --git a/include/grpc++/client_context.h b/include/grpc++/client_context.h index 7adaaa6e6f..9df76699d2 100644 --- a/include/grpc++/client_context.h +++ b/include/grpc++/client_context.h @@ -38,6 +38,7 @@ #include <memory> #include <string> +#include <grpc/compression.h> #include <grpc/support/log.h> #include <grpc/support/time.h> #include <grpc++/auth_context.h> @@ -109,6 +110,12 @@ class ClientContext { creds_ = creds; } + grpc_compression_algorithm get_compression_algorithm() const { + return compression_algorithm_; + } + + void set_compression_algorithm(grpc_compression_algorithm algorithm); + std::shared_ptr<const AuthContext> auth_context() const; // Get and set census context @@ -167,6 +174,8 @@ class ClientContext { std::multimap<grpc::string, grpc::string> send_initial_metadata_; std::multimap<grpc::string, grpc::string> recv_initial_metadata_; std::multimap<grpc::string, grpc::string> trailing_metadata_; + + grpc_compression_algorithm compression_algorithm_; }; } // namespace grpc diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h index f32cbff06c..0523ab6a0e 100644 --- a/include/grpc++/completion_queue.h +++ b/include/grpc++/completion_queue.h @@ -105,7 +105,8 @@ class CompletionQueue : public GrpcLibrary { // Returns false if the queue is ready for destruction, true if event bool Next(void** tag, bool* ok) { - return (AsyncNextInternal(tag, ok, gpr_inf_future) != SHUTDOWN); + return (AsyncNextInternal(tag, ok, gpr_inf_future(GPR_CLOCK_REALTIME)) != + SHUTDOWN); } // Shutdown has to be called, and the CompletionQueue can only be diff --git a/include/grpc++/fixed_size_thread_pool.h b/include/grpc++/fixed_size_thread_pool.h index 9f0cbfbae9..307e166142 100644 --- a/include/grpc++/fixed_size_thread_pool.h +++ b/include/grpc++/fixed_size_thread_pool.h @@ -31,8 +31,8 @@ * */ -#ifndef GRPC_INTERNAL_CPP_SERVER_THREAD_POOL_H -#define GRPC_INTERNAL_CPP_SERVER_THREAD_POOL_H +#ifndef GRPCXX_FIXED_SIZE_THREAD_POOL_H +#define GRPCXX_FIXED_SIZE_THREAD_POOL_H #include <grpc++/config.h> @@ -50,7 +50,7 @@ class FixedSizeThreadPool GRPC_FINAL : public ThreadPoolInterface { explicit FixedSizeThreadPool(int num_threads); ~FixedSizeThreadPool(); - void ScheduleCallback(const std::function<void()>& callback) GRPC_OVERRIDE; + void Add(const std::function<void()>& callback) GRPC_OVERRIDE; private: grpc::mutex mu_; @@ -64,4 +64,4 @@ class FixedSizeThreadPool GRPC_FINAL : public ThreadPoolInterface { } // namespace grpc -#endif // GRPC_INTERNAL_CPP_SERVER_THREAD_POOL_H +#endif // GRPCXX_FIXED_SIZE_THREAD_POOL_H diff --git a/include/grpc++/server_context.h b/include/grpc++/server_context.h index 6f094eda3d..3bfa48fbb6 100644 --- a/include/grpc++/server_context.h +++ b/include/grpc++/server_context.h @@ -37,6 +37,7 @@ #include <map> #include <memory> +#include <grpc/compression.h> #include <grpc/support/time.h> #include <grpc++/auth_context.h> #include <grpc++/config.h> @@ -103,6 +104,16 @@ class ServerContext { return client_metadata_; } + grpc_compression_level get_compression_level() const { + return compression_level_; + } + void set_compression_level(grpc_compression_level level); + + grpc_compression_algorithm get_compression_algorithm() const { + return compression_algorithm_; + } + void set_compression_algorithm(grpc_compression_algorithm algorithm); + std::shared_ptr<const AuthContext> auth_context() const; private: @@ -154,6 +165,9 @@ class ServerContext { std::multimap<grpc::string, grpc::string> client_metadata_; std::multimap<grpc::string, grpc::string> initial_metadata_; std::multimap<grpc::string, grpc::string> trailing_metadata_; + + grpc_compression_level compression_level_; + grpc_compression_algorithm compression_algorithm_; }; } // namespace grpc diff --git a/include/grpc++/thread_pool_interface.h b/include/grpc++/thread_pool_interface.h index ac4458d530..d080b31dcc 100644 --- a/include/grpc++/thread_pool_interface.h +++ b/include/grpc++/thread_pool_interface.h @@ -44,7 +44,7 @@ class ThreadPoolInterface { virtual ~ThreadPoolInterface() {} // Schedule the given callback for execution. - virtual void ScheduleCallback(const std::function<void()>& callback) = 0; + virtual void Add(const std::function<void()>& callback) = 0; }; ThreadPoolInterface* CreateDefaultThreadPool(); diff --git a/include/grpc/compression.h b/include/grpc/compression.h index 61bce05b50..913e553ba9 100644 --- a/include/grpc/compression.h +++ b/include/grpc/compression.h @@ -34,8 +34,12 @@ #ifndef GRPC_COMPRESSION_H #define GRPC_COMPRESSION_H +#ifdef __cplusplus +extern "C" { +#endif + /** To be used in channel arguments */ -#define GRPC_COMPRESSION_LEVEL_ARG "grpc.compression_level" +#define GRPC_COMPRESSION_ALGORITHM_ARG "grpc.compression_algorithm" /* The various compression algorithms supported by GRPC */ typedef enum { @@ -50,13 +54,34 @@ typedef enum { GRPC_COMPRESS_LEVEL_NONE = 0, GRPC_COMPRESS_LEVEL_LOW, GRPC_COMPRESS_LEVEL_MED, - GRPC_COMPRESS_LEVEL_HIGH + GRPC_COMPRESS_LEVEL_HIGH, + GRPC_COMPRESS_LEVEL_COUNT } grpc_compression_level; -const char *grpc_compression_algorithm_name( +/** Parses \a name as a grpc_compression_algorithm instance, updating \a + * algorithm. Returns 1 upon success, 0 otherwise. */ +int grpc_compression_algorithm_parse(const char *name, + grpc_compression_algorithm *algorithm); + +/** Updates \a name with the encoding name corresponding to a valid \a + * algorithm. Returns 1 upon success, 0 otherwise. */ +int grpc_compression_algorithm_name(grpc_compression_algorithm algorithm, + char **name); + +/** Returns the compression level corresponding to \a algorithm. + * + * It abort()s for unknown algorithms. */ +grpc_compression_level grpc_compression_level_for_algorithm( grpc_compression_algorithm algorithm); +/** Returns the compression algorithm corresponding to \a level. + * + * It abort()s for unknown levels . */ grpc_compression_algorithm grpc_compression_algorithm_for_level( grpc_compression_level level); +#ifdef __cplusplus +} +#endif + #endif /* GRPC_COMPRESSION_H */ diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index ad0bf7d663..137bd0ac53 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -45,40 +45,49 @@ extern "C" { #endif -/* Completion Queues enable notification of the completion of asynchronous - actions. */ +/*! \mainpage GRPC Core + * + * \section intro_sec The GRPC Core library is a low-level library designed + * to be wrapped by higher level libraries. + * + * The top-level API is provided in grpc.h. + * Security related functionality lives in grpc_security.h. + */ + +/** Completion Queues enable notification of the completion of asynchronous + actions. */ typedef struct grpc_completion_queue grpc_completion_queue; -/* The Channel interface allows creation of Call objects. */ +/** The Channel interface allows creation of Call objects. */ typedef struct grpc_channel grpc_channel; -/* A server listens to some port and responds to request calls */ +/** A server listens to some port and responds to request calls */ typedef struct grpc_server grpc_server; -/* A Call represents an RPC. When created, it is in a configuration state - allowing properties to be set until it is invoked. After invoke, the Call - can have messages written to it and read from it. */ +/** A Call represents an RPC. When created, it is in a configuration state + allowing properties to be set until it is invoked. After invoke, the Call + can have messages written to it and read from it. */ typedef struct grpc_call grpc_call; -/* Type specifier for grpc_arg */ +/** Type specifier for grpc_arg */ typedef enum { GRPC_ARG_STRING, GRPC_ARG_INTEGER, GRPC_ARG_POINTER } grpc_arg_type; -/* A single argument... each argument has a key and a value +/** A single argument... each argument has a key and a value - A note on naming keys: - Keys are namespaced into groups, usually grouped by library, and are - keys for module XYZ are named XYZ.key1, XYZ.key2, etc. Module names must - be restricted to the regex [A-Za-z][_A-Za-z0-9]{,15}. - Key names must be restricted to the regex [A-Za-z][_A-Za-z0-9]{,47}. + A note on naming keys: + Keys are namespaced into groups, usually grouped by library, and are + keys for module XYZ are named XYZ.key1, XYZ.key2, etc. Module names must + be restricted to the regex [A-Za-z][_A-Za-z0-9]{,15}. + Key names must be restricted to the regex [A-Za-z][_A-Za-z0-9]{,47}. - GRPC core library keys are prefixed by grpc. + GRPC core library keys are prefixed by grpc. - Library authors are strongly encouraged to #define symbolic constants for - their keys so that it's possible to change them in the future. */ + Library authors are strongly encouraged to \#define symbolic constants for + their keys so that it's possible to change them in the future. */ typedef struct { grpc_arg_type type; char *key; @@ -107,14 +116,14 @@ typedef struct { } grpc_channel_args; /* Channel argument keys: */ -/* Enable census for tracing and stats collection */ +/** Enable census for tracing and stats collection */ #define GRPC_ARG_ENABLE_CENSUS "grpc.census" -/* Maximum number of concurrent incoming streams to allow on a http2 - connection */ +/** Maximum number of concurrent incoming streams to allow on a http2 + connection */ #define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams" -/* Maximum message length that the channel can receive */ +/** Maximum message length that the channel can receive */ #define GRPC_ARG_MAX_MESSAGE_LENGTH "grpc.max_message_length" -/* Initial sequence number for http2 transports */ +/** Initial sequence number for http2 transports */ #define GRPC_ARG_HTTP2_INITIAL_SEQUENCE_NUMBER \ "grpc.http2.initial_sequence_number" @@ -132,59 +141,59 @@ typedef enum { GRPC_CHANNEL_FATAL_FAILURE } grpc_connectivity_state; -/* Result of a grpc call. If the caller satisfies the prerequisites of a - particular operation, the grpc_call_error returned will be GRPC_CALL_OK. - Receiving any other value listed here is an indication of a bug in the - caller. */ +/** Result of a grpc call. If the caller satisfies the prerequisites of a + particular operation, the grpc_call_error returned will be GRPC_CALL_OK. + Receiving any other value listed here is an indication of a bug in the + caller. */ typedef enum grpc_call_error { - /* everything went ok */ + /** everything went ok */ GRPC_CALL_OK = 0, - /* something failed, we don't know what */ + /** something failed, we don't know what */ GRPC_CALL_ERROR, - /* this method is not available on the server */ + /** this method is not available on the server */ GRPC_CALL_ERROR_NOT_ON_SERVER, - /* this method is not available on the client */ + /** this method is not available on the client */ GRPC_CALL_ERROR_NOT_ON_CLIENT, - /* this method must be called before server_accept */ + /** this method must be called before server_accept */ GRPC_CALL_ERROR_ALREADY_ACCEPTED, - /* this method must be called before invoke */ + /** this method must be called before invoke */ GRPC_CALL_ERROR_ALREADY_INVOKED, - /* this method must be called after invoke */ + /** this method must be called after invoke */ GRPC_CALL_ERROR_NOT_INVOKED, - /* this call is already finished - (writes_done or write_status has already been called) */ + /** this call is already finished + (writes_done or write_status has already been called) */ GRPC_CALL_ERROR_ALREADY_FINISHED, - /* there is already an outstanding read/write operation on the call */ + /** there is already an outstanding read/write operation on the call */ GRPC_CALL_ERROR_TOO_MANY_OPERATIONS, - /* the flags value was illegal for this call */ + /** the flags value was illegal for this call */ GRPC_CALL_ERROR_INVALID_FLAGS, - /* invalid metadata was passed to this call */ + /** invalid metadata was passed to this call */ GRPC_CALL_ERROR_INVALID_METADATA, - /* completion queue for notification has not been registered with the server - */ + /** completion queue for notification has not been registered with the + server */ GRPC_CALL_ERROR_NOT_SERVER_COMPLETION_QUEUE } grpc_call_error; /* Write Flags: */ -/* Hint that the write may be buffered and need not go out on the wire - immediately. GRPC is free to buffer the message until the next non-buffered - write, or until writes_done, but it need not buffer completely or at all. */ +/** Hint that the write may be buffered and need not go out on the wire + immediately. GRPC is free to buffer the message until the next non-buffered + write, or until writes_done, but it need not buffer completely or at all. */ #define GRPC_WRITE_BUFFER_HINT (0x00000001u) -/* Force compression to be disabled for a particular write - (start_write/add_metadata). Illegal on invoke/accept. */ +/** Force compression to be disabled for a particular write + (start_write/add_metadata). Illegal on invoke/accept. */ #define GRPC_WRITE_NO_COMPRESS (0x00000002u) -/* Mask of all valid flags. */ +/** Mask of all valid flags. */ #define GRPC_WRITE_USED_MASK (GRPC_WRITE_BUFFER_HINT | GRPC_WRITE_NO_COMPRESS) -/* A single metadata element */ +/** A single metadata element */ typedef struct grpc_metadata { const char *key; const char *value; size_t value_length; - /* The following fields are reserved for grpc internal use. - There is no need to initialize them, and they will be set to garbage during - calls to grpc. */ + /** The following fields are reserved for grpc internal use. + There is no need to initialize them, and they will be set to garbage during + calls to grpc. */ struct { void *obfuscated[3]; } internal_data; @@ -235,42 +244,41 @@ void grpc_call_details_init(grpc_call_details *details); void grpc_call_details_destroy(grpc_call_details *details); typedef enum { - /* Send initial metadata: one and only one instance MUST be sent for each - call, - unless the call was cancelled - in which case this can be skipped */ + /** Send initial metadata: one and only one instance MUST be sent for each + call, unless the call was cancelled - in which case this can be skipped */ GRPC_OP_SEND_INITIAL_METADATA = 0, - /* Send a message: 0 or more of these operations can occur for each call */ + /** Send a message: 0 or more of these operations can occur for each call */ GRPC_OP_SEND_MESSAGE, - /* Send a close from the client: one and only one instance MUST be sent from - the client, - unless the call was cancelled - in which case this can be skipped */ + /** Send a close from the client: one and only one instance MUST be sent from + the client, unless the call was cancelled - in which case this can be + skipped */ GRPC_OP_SEND_CLOSE_FROM_CLIENT, - /* Send status from the server: one and only one instance MUST be sent from - the server - unless the call was cancelled - in which case this can be skipped */ + /** Send status from the server: one and only one instance MUST be sent from + the server unless the call was cancelled - in which case this can be + skipped */ GRPC_OP_SEND_STATUS_FROM_SERVER, - /* Receive initial metadata: one and only one MUST be made on the client, must - not be made on the server */ + /** Receive initial metadata: one and only one MUST be made on the client, + must not be made on the server */ GRPC_OP_RECV_INITIAL_METADATA, - /* Receive a message: 0 or more of these operations can occur for each call */ + /** Receive a message: 0 or more of these operations can occur for each call */ GRPC_OP_RECV_MESSAGE, - /* Receive status on the client: one and only one must be made on the client. + /** Receive status on the client: one and only one must be made on the client. This operation always succeeds, meaning ops paired with this operation will also appear to succeed, even though they may not have. In that case - the status will indicate some failure. - */ + the status will indicate some failure. */ GRPC_OP_RECV_STATUS_ON_CLIENT, - /* Receive close on the server: one and only one must be made on the server - */ + /** Receive close on the server: one and only one must be made on the + server */ GRPC_OP_RECV_CLOSE_ON_SERVER } grpc_op_type; -/* Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT - which has - no arguments) */ +/** Operation data: one field for each op type (except SEND_CLOSE_FROM_CLIENT + which has no arguments) */ typedef struct grpc_op { + /** Operation type, as defined by grpc_op_type */ grpc_op_type op; - gpr_uint32 flags; /**< Write flags bitset for grpc_begin_messages */ + /** Write flags bitset for grpc_begin_messages */ + gpr_uint32 flags; union { struct { size_t count; @@ -283,53 +291,49 @@ typedef struct grpc_op { grpc_status_code status; const char *status_details; } send_status_from_server; - /* ownership of the array is with the caller, but ownership of the elements - stays with the call object (ie key, value members are owned by the call - object, recv_initial_metadata->array is owned by the caller). - After the operation completes, call grpc_metadata_array_destroy on this - value, or reuse it in a future op. */ + /** ownership of the array is with the caller, but ownership of the elements + stays with the call object (ie key, value members are owned by the call + object, recv_initial_metadata->array is owned by the caller). + After the operation completes, call grpc_metadata_array_destroy on this + value, or reuse it in a future op. */ grpc_metadata_array *recv_initial_metadata; - /* ownership of the byte buffer is moved to the caller; the caller must call - grpc_byte_buffer_destroy on this value, or reuse it in a future op. */ + /** ownership of the byte buffer is moved to the caller; the caller must call + grpc_byte_buffer_destroy on this value, or reuse it in a future op. */ grpc_byte_buffer **recv_message; struct { - /* ownership of the array is with the caller, but ownership of the - elements - stays with the call object (ie key, value members are owned by the call - object, trailing_metadata->array is owned by the caller). - After the operation completes, call grpc_metadata_array_destroy on this - value, or reuse it in a future op. */ + /** ownership of the array is with the caller, but ownership of the + elements stays with the call object (ie key, value members are owned + by the call object, trailing_metadata->array is owned by the caller). + After the operation completes, call grpc_metadata_array_destroy on this + value, or reuse it in a future op. */ grpc_metadata_array *trailing_metadata; grpc_status_code *status; - /* status_details is a buffer owned by the application before the op - completes - and after the op has completed. During the operation status_details may - be - reallocated to a size larger than *status_details_capacity, in which - case - *status_details_capacity will be updated with the new array capacity. - - Pre-allocating space: - size_t my_capacity = 8; - char *my_details = gpr_malloc(my_capacity); - x.status_details = &my_details; - x.status_details_capacity = &my_capacity; - - Not pre-allocating space: - size_t my_capacity = 0; - char *my_details = NULL; - x.status_details = &my_details; - x.status_details_capacity = &my_capacity; - - After the call: - gpr_free(my_details); */ + /** status_details is a buffer owned by the application before the op + completes and after the op has completed. During the operation + status_details may be reallocated to a size larger than + *status_details_capacity, in which case *status_details_capacity will + be updated with the new array capacity. + + Pre-allocating space: + size_t my_capacity = 8; + char *my_details = gpr_malloc(my_capacity); + x.status_details = &my_details; + x.status_details_capacity = &my_capacity; + + Not pre-allocating space: + size_t my_capacity = 0; + char *my_details = NULL; + x.status_details = &my_details; + x.status_details_capacity = &my_capacity; + + After the call: + gpr_free(my_details); */ char **status_details; size_t *status_details_capacity; } recv_status_on_client; struct { - /* out argument, set to 1 if the call failed in any way (seen as a - cancellation - on the server), or 0 if the call succeeded */ + /** out argument, set to 1 if the call failed in any way (seen as a + cancellation on the server), or 0 if the call succeeded */ int *cancelled; } recv_close_on_server; } data; @@ -385,62 +389,62 @@ grpc_event grpc_completion_queue_next(grpc_completion_queue *cq, grpc_event grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag, gpr_timespec deadline); -/* Begin destruction of a completion queue. Once all possible events are - drained then grpc_completion_queue_next will start to produce - GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call - grpc_completion_queue_destroy. +/** Begin destruction of a completion queue. Once all possible events are + drained then grpc_completion_queue_next will start to produce + GRPC_QUEUE_SHUTDOWN events only. At that point it's safe to call + grpc_completion_queue_destroy. - After calling this function applications should ensure that no - NEW work is added to be published on this completion queue. */ + After calling this function applications should ensure that no + NEW work is added to be published on this completion queue. */ void grpc_completion_queue_shutdown(grpc_completion_queue *cq); -/* Destroy a completion queue. The caller must ensure that the queue is - drained and no threads are executing grpc_completion_queue_next */ +/** Destroy a completion queue. The caller must ensure that the queue is + drained and no threads are executing grpc_completion_queue_next */ void grpc_completion_queue_destroy(grpc_completion_queue *cq); -/* Create a call given a grpc_channel, in order to call 'method'. All - completions are sent to 'completion_queue'. 'method' and 'host' need only - live through the invocation of this function. */ +/** Create a call given a grpc_channel, in order to call 'method'. All + completions are sent to 'completion_queue'. 'method' and 'host' need only + live through the invocation of this function. */ grpc_call *grpc_channel_create_call(grpc_channel *channel, grpc_completion_queue *completion_queue, const char *method, const char *host, gpr_timespec deadline); -/* Pre-register a method/host pair on a channel. */ +/** Pre-register a method/host pair on a channel. */ void *grpc_channel_register_call(grpc_channel *channel, const char *method, const char *host); -/* Create a call given a handle returned from grpc_channel_register_call */ +/** Create a call given a handle returned from grpc_channel_register_call */ grpc_call *grpc_channel_create_registered_call( grpc_channel *channel, grpc_completion_queue *completion_queue, void *registered_call_handle, gpr_timespec deadline); -/* Start a batch of operations defined in the array ops; when complete, post a - completion of type 'tag' to the completion queue bound to the call. - The order of ops specified in the batch has no significance. - Only one operation of each type can be active at once in any given - batch. You must call grpc_completion_queue_next or - grpc_completion_queue_pluck on the completion queue associated with 'call' - for work to be performed. - THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment - needs to be synchronized. As an optimization, you may synchronize batches - containing just send operations independently from batches containing just - receive operations. */ +/** Start a batch of operations defined in the array ops; when complete, post a + completion of type 'tag' to the completion queue bound to the call. + The order of ops specified in the batch has no significance. + Only one operation of each type can be active at once in any given + batch. You must call grpc_completion_queue_next or + grpc_completion_queue_pluck on the completion queue associated with 'call' + for work to be performed. + THREAD SAFETY: access to grpc_call_start_batch in multi-threaded environment + needs to be synchronized. As an optimization, you may synchronize batches + containing just send operations independently from batches containing just + receive operations. */ grpc_call_error grpc_call_start_batch(grpc_call *call, const grpc_op *ops, size_t nops, void *tag); -/* Create a client channel to 'target'. Additional channel level configuration - MAY be provided by grpc_channel_args, though the expectation is that most - clients will want to simply pass NULL. See grpc_channel_args definition for - more on this. The data in 'args' need only live through the invocation of - this function. */ +/** Create a client channel to 'target'. Additional channel level configuration + MAY be provided by grpc_channel_args, though the expectation is that most + clients will want to simply pass NULL. See grpc_channel_args definition for + more on this. The data in 'args' need only live through the invocation of + this function. */ grpc_channel *grpc_channel_create(const char *target, const grpc_channel_args *args); -/* Create a lame client: this client fails every operation attempted on it. */ +/** Create a lame client: this client fails every operation attempted on it. */ grpc_channel *grpc_lame_client_channel_create(void); -/* Close and destroy a grpc channel */ +/** Close and destroy a grpc channel */ void grpc_channel_destroy(grpc_channel *channel); /* Error handling for grpc_call @@ -449,49 +453,49 @@ void grpc_channel_destroy(grpc_channel *channel); If a grpc_call fails, it's guaranteed that no change to the call state has been made. */ -/* Called by clients to cancel an RPC on the server. - Can be called multiple times, from any thread. - THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status - are thread-safe, and can be called at any point before grpc_call_destroy - is called.*/ +/** Called by clients to cancel an RPC on the server. + Can be called multiple times, from any thread. + THREAD-SAFETY grpc_call_cancel and grpc_call_cancel_with_status + are thread-safe, and can be called at any point before grpc_call_destroy + is called.*/ grpc_call_error grpc_call_cancel(grpc_call *call); -/* Called by clients to cancel an RPC on the server. - Can be called multiple times, from any thread. - If a status has not been received for the call, set it to the status code - and description passed in. - Importantly, this function does not send status nor description to the - remote endpoint. */ +/** Called by clients to cancel an RPC on the server. + Can be called multiple times, from any thread. + If a status has not been received for the call, set it to the status code + and description passed in. + Importantly, this function does not send status nor description to the + remote endpoint. */ grpc_call_error grpc_call_cancel_with_status(grpc_call *call, grpc_status_code status, const char *description); -/* Destroy a call. - THREAD SAFETY: grpc_call_destroy is thread-compatible */ +/** Destroy a call. + THREAD SAFETY: grpc_call_destroy is thread-compatible */ void grpc_call_destroy(grpc_call *call); -/* Request notification of a new call. 'cq_for_notification' must - have been registered to the server via grpc_server_register_completion_queue. - */ +/** Request notification of a new call. 'cq_for_notification' must + have been registered to the server via + grpc_server_register_completion_queue. */ grpc_call_error grpc_server_request_call( grpc_server *server, grpc_call **call, grpc_call_details *details, grpc_metadata_array *request_metadata, grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_for_notification, void *tag_new); -/* Registers a method in the server. - Methods to this (host, method) pair will not be reported by - grpc_server_request_call, but instead be reported by - grpc_server_request_registered_call when passed the appropriate - registered_method (as returned by this function). - Must be called before grpc_server_start. - Returns NULL on failure. */ +/** Registers a method in the server. + Methods to this (host, method) pair will not be reported by + grpc_server_request_call, but instead be reported by + grpc_server_request_registered_call when passed the appropriate + registered_method (as returned by this function). + Must be called before grpc_server_start. + Returns NULL on failure. */ void *grpc_server_register_method(grpc_server *server, const char *method, const char *host); -/* Request notification of a new pre-registered call. 'cq_for_notification' must - have been registered to the server via grpc_server_register_completion_queue. - */ +/** Request notification of a new pre-registered call. 'cq_for_notification' + must have been registered to the server via + grpc_server_register_completion_queue. */ grpc_call_error grpc_server_request_registered_call( grpc_server *server, void *registered_method, grpc_call **call, gpr_timespec *deadline, grpc_metadata_array *request_metadata, @@ -499,45 +503,45 @@ grpc_call_error grpc_server_request_registered_call( grpc_completion_queue *cq_bound_to_call, grpc_completion_queue *cq_for_notification, void *tag_new); -/* Create a server. Additional configuration for each incoming channel can - be specified with args. If no additional configuration is needed, args can - be NULL. See grpc_channel_args for more. The data in 'args' need only live - through the invocation of this function. */ +/** Create a server. Additional configuration for each incoming channel can + be specified with args. If no additional configuration is needed, args can + be NULL. See grpc_channel_args for more. The data in 'args' need only live + through the invocation of this function. */ grpc_server *grpc_server_create(const grpc_channel_args *args); -/* Register a completion queue with the server. Must be done for any - notification completion queue that is passed to grpc_server_request_*_call - and to grpc_server_shutdown_and_notify. Must be performed prior to - grpc_server_start. */ +/** Register a completion queue with the server. Must be done for any + notification completion queue that is passed to grpc_server_request_*_call + and to grpc_server_shutdown_and_notify. Must be performed prior to + grpc_server_start. */ void grpc_server_register_completion_queue(grpc_server *server, grpc_completion_queue *cq); -/* Add a HTTP2 over plaintext over tcp listener. - Returns bound port number on success, 0 on failure. - REQUIRES: server not started */ +/** Add a HTTP2 over plaintext over tcp listener. + Returns bound port number on success, 0 on failure. + REQUIRES: server not started */ int grpc_server_add_http2_port(grpc_server *server, const char *addr); -/* Start a server - tells all listeners to start listening */ +/** Start a server - tells all listeners to start listening */ void grpc_server_start(grpc_server *server); -/* Begin shutting down a server. - After completion, no new calls or connections will be admitted. - Existing calls will be allowed to complete. - Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. - Shutdown is idempotent, and all tags will be notified at once if multiple - grpc_server_shutdown_and_notify calls are made. 'cq' must have been - registered to this server via grpc_server_register_completion_queue. */ +/** Begin shutting down a server. + After completion, no new calls or connections will be admitted. + Existing calls will be allowed to complete. + Send a GRPC_OP_COMPLETE event when there are no more calls being serviced. + Shutdown is idempotent, and all tags will be notified at once if multiple + grpc_server_shutdown_and_notify calls are made. 'cq' must have been + registered to this server via grpc_server_register_completion_queue. */ void grpc_server_shutdown_and_notify(grpc_server *server, grpc_completion_queue *cq, void *tag); -/* Cancel all in-progress calls. - Only usable after shutdown. */ +/** Cancel all in-progress calls. + Only usable after shutdown. */ void grpc_server_cancel_all_calls(grpc_server *server); -/* Destroy a server. - Shutdown must have completed beforehand (i.e. all tags generated by - grpc_server_shutdown_and_notify must have been received, and at least - one call to grpc_server_shutdown_and_notify must have been made). */ +/** Destroy a server. + Shutdown must have completed beforehand (i.e. all tags generated by + grpc_server_shutdown_and_notify must have been received, and at least + one call to grpc_server_shutdown_and_notify must have been made). */ void grpc_server_destroy(grpc_server *server); /** Enable or disable a tracer. diff --git a/include/grpc/support/time.h b/include/grpc/support/time.h index a5c947dfc8..3f375f6ecd 100644 --- a/include/grpc/support/time.h +++ b/include/grpc/support/time.h @@ -45,15 +45,30 @@ extern "C" { #endif +/* The clocks we support. */ +typedef enum { + /* Monotonic clock. Epoch undefined. Always moves forwards. */ + GPR_CLOCK_MONOTONIC = 0, + /* Realtime clock. May jump forwards or backwards. Settable by + the system administrator. Has its epoch at 0:00:00 UTC 1 Jan 1970. */ + GPR_CLOCK_REALTIME, + /* Unmeasurable clock type: no base, created by taking the difference + between two times */ + GPR_TIMESPAN +} gpr_clock_type; + typedef struct gpr_timespec { time_t tv_sec; int tv_nsec; + /** Against which clock was this time measured? (or GPR_TIMESPAN if + this is a relative time meaure) */ + gpr_clock_type clock_type; } gpr_timespec; /* Time constants. */ -extern const gpr_timespec gpr_time_0; /* The zero time interval. */ -extern const gpr_timespec gpr_inf_future; /* The far future */ -extern const gpr_timespec gpr_inf_past; /* The far past. */ +gpr_timespec gpr_time_0(gpr_clock_type type); /* The zero time interval. */ +gpr_timespec gpr_inf_future(gpr_clock_type type); /* The far future */ +gpr_timespec gpr_inf_past(gpr_clock_type type); /* The far past. */ #define GPR_MS_PER_SEC 1000 #define GPR_US_PER_SEC 1000000 @@ -62,15 +77,6 @@ extern const gpr_timespec gpr_inf_past; /* The far past. */ #define GPR_NS_PER_US 1000 #define GPR_US_PER_MS 1000 -/* The clocks we support. */ -typedef enum { - /* Monotonic clock. Epoch undefined. Always moves forwards. */ - GPR_CLOCK_MONOTONIC = 0, - /* Realtime clock. May jump forwards or backwards. Settable by - the system administrator. Has its epoch at 0:00:00 UTC 1 Jan 1970. */ - GPR_CLOCK_REALTIME -} gpr_clock_type; - /* initialize time subsystem */ void gpr_time_init(void); @@ -90,12 +96,12 @@ gpr_timespec gpr_time_sub(gpr_timespec a, gpr_timespec b); /* Return a timespec representing a given number of time units. LONG_MIN is interpreted as gpr_inf_past, and LONG_MAX as gpr_inf_future. */ -gpr_timespec gpr_time_from_micros(long x); -gpr_timespec gpr_time_from_nanos(long x); -gpr_timespec gpr_time_from_millis(long x); -gpr_timespec gpr_time_from_seconds(long x); -gpr_timespec gpr_time_from_minutes(long x); -gpr_timespec gpr_time_from_hours(long x); +gpr_timespec gpr_time_from_micros(long x, gpr_clock_type clock_type); +gpr_timespec gpr_time_from_nanos(long x, gpr_clock_type clock_type); +gpr_timespec gpr_time_from_millis(long x, gpr_clock_type clock_type); +gpr_timespec gpr_time_from_seconds(long x, gpr_clock_type clock_type); +gpr_timespec gpr_time_from_minutes(long x, gpr_clock_type clock_type); +gpr_timespec gpr_time_from_hours(long x, gpr_clock_type clock_type); gpr_int32 gpr_time_to_millis(gpr_timespec timespec); |