diff options
Diffstat (limited to 'include/grpc/grpc.h')
| -rw-r--r-- | include/grpc/grpc.h | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h new file mode 100644 index 0000000000..17e155a929 --- /dev/null +++ b/include/grpc/grpc.h @@ -0,0 +1,421 @@ +/* + * + * Copyright 2014, Google Inc. + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are + * met: + * + * * Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * * Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following disclaimer + * in the documentation and/or other materials provided with the + * distribution. + * * Neither the name of Google Inc. nor the names of its + * contributors may be used to endorse or promote products derived from + * this software without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT + * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, + * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY + * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE + * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ + +#ifndef __GRPC_GRPC_H__ +#define __GRPC_GRPC_H__ + +#include <grpc/status.h> + +#include <stddef.h> +#include <grpc/support/slice.h> +#include <grpc/support/time.h> + +#ifdef __cplusplus +extern "C" { +#endif + +/* Completion Channels enable notification of the completion of asynchronous + actions. */ +typedef struct grpc_completion_queue grpc_completion_queue; + +/* 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 */ +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. */ +typedef struct grpc_call grpc_call; + +/* 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 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. + + 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; + union { + char *string; + int integer; + struct { + void *p; + void *(*copy)(void *p); + void (*destroy)(void *p); + } pointer; + } value; +} grpc_arg; + +/* An array of arguments that can be passed around */ +typedef struct { + size_t num_args; + grpc_arg *args; +} grpc_channel_args; + +/* Channel argument keys: */ +/* 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 */ +#define GRPC_ARG_MAX_CONCURRENT_STREAMS "grpc.max_concurrent_streams" +/* Maximum message length that the channel can receive */ +#define GRPC_ARG_MAX_MESSAGE_LENGTH "grpc.max_message_length" + +/* Status of a completed call */ +typedef struct grpc_status { + grpc_status_code code; + char *details; +} grpc_status; + +/* 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 */ + GRPC_CALL_OK = 0, + /* something failed, we don't know what */ + GRPC_CALL_ERROR, + /* this method is not available on the server */ + GRPC_CALL_ERROR_NOT_ON_SERVER, + /* this method is not available on the client */ + GRPC_CALL_ERROR_NOT_ON_CLIENT, + /* this method must be called before invoke */ + GRPC_CALL_ERROR_ALREADY_INVOKED, + /* 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) */ + GRPC_CALL_ERROR_ALREADY_FINISHED, + /* 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 */ + GRPC_CALL_ERROR_INVALID_FLAGS +} grpc_call_error; + +/* Result of a grpc operation */ +typedef enum grpc_op_error { + /* everything went ok */ + GRPC_OP_OK = 0, + /* something failed, we don't know what */ + GRPC_OP_ERROR +} grpc_op_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. */ +#define GRPC_WRITE_BUFFER_HINT (0x00000001u) +/* Force compression to be disabled for a particular write + (start_write/add_metadata). Illegal on invoke/accept. */ +#define GRPC_WRITE_NO_COMPRESS (0x00000002u) + +/* A buffer of bytes */ +struct grpc_byte_buffer; +typedef struct grpc_byte_buffer grpc_byte_buffer; + +/* Sample helpers to obtain byte buffers (these will certainly move place */ +grpc_byte_buffer *grpc_byte_buffer_create(gpr_slice *slices, size_t nslices); +size_t grpc_byte_buffer_length(grpc_byte_buffer *bb); +void grpc_byte_buffer_destroy(grpc_byte_buffer *byte_buffer); + +/* Reader for byte buffers. Iterates over slices in the byte buffer */ +struct grpc_byte_buffer_reader; +typedef struct grpc_byte_buffer_reader grpc_byte_buffer_reader; + +grpc_byte_buffer_reader *grpc_byte_buffer_reader_create( + grpc_byte_buffer *buffer); +/* At the end of the stream, returns 0. Otherwise, returns 1 and sets slice to + be the returned slice. Caller is responsible for calling gpr_slice_unref on + the result. */ +int grpc_byte_buffer_reader_next(grpc_byte_buffer_reader *reader, + gpr_slice *slice); +void grpc_byte_buffer_reader_destroy(grpc_byte_buffer_reader *reader); + +/* A single metadata element */ +typedef struct grpc_metadata { + char *key; + char *value; + size_t value_length; +} grpc_metadata; + +typedef enum grpc_completion_type { + GRPC_QUEUE_SHUTDOWN, /* Shutting down */ + GRPC_READ, /* A read has completed */ + GRPC_INVOKE_ACCEPTED, /* An invoke call has been accepted by flow + control */ + GRPC_WRITE_ACCEPTED, /* A write has been accepted by + flow control */ + GRPC_FINISH_ACCEPTED, /* writes_done or write_status has been accepted */ + GRPC_CLIENT_METADATA_READ, /* The metadata array sent by server received at + client */ + GRPC_FINISHED, /* An RPC has finished. The event contains status. + On the server this will be OK or Cancelled. */ + GRPC_SERVER_RPC_NEW, /* A new RPC has arrived at the server */ + GRPC_COMPLETION_DO_NOT_USE /* must be last, forces users to include + a default: case */ +} grpc_completion_type; + +typedef struct grpc_event { + grpc_completion_type type; + void *tag; + grpc_call *call; + /* Data associated with the completion type. Field names match the type of + completion as listed in grpc_completion_type. */ + union { + /* Contains a pointer to the buffer that was read, or NULL at the end of a + stream. */ + grpc_byte_buffer *read; + grpc_op_error write_accepted; + grpc_op_error finish_accepted; + grpc_op_error invoke_accepted; + struct { + size_t count; + grpc_metadata *elements; + } client_metadata_read; + grpc_status finished; + struct { + const char *method; + const char *host; + gpr_timespec deadline; + size_t metadata_count; + grpc_metadata *metadata_elements; + } server_rpc_new; + } data; +} grpc_event; + +/* Initialize the grpc library */ +void grpc_init(); + +/* Shutdown the grpc library */ +void grpc_shutdown(); + +grpc_completion_queue *grpc_completion_queue_create(); + +/* Blocks until an event is available, the completion queue is being shutdown, + or deadline is reached. Returns NULL on timeout, otherwise the event that + occurred. Callers should call grpc_event_finish once they have processed + the event. + + Callers must not call grpc_completion_queue_next and + grpc_completion_queue_pluck simultaneously on the same completion queue. */ +grpc_event *grpc_completion_queue_next(grpc_completion_queue *cq, + gpr_timespec deadline); + +/* Blocks until an event with tag 'tag' is available, the completion queue is + being shutdown or deadline is reached. Returns NULL on timeout, or a pointer + to the event that occurred. Callers should call grpc_event_finish once they + have processed the event. + + Callers must not call grpc_completion_queue_next and + grpc_completion_queue_pluck simultaneously on the same completion queue. */ +grpc_event *grpc_completion_queue_pluck(grpc_completion_queue *cq, void *tag, + gpr_timespec deadline); + +/* Cleanup any data owned by the event */ +void grpc_event_finish(grpc_event *event); + +/* Begin destruction of a completion queue. Once all possible events are + drained it's safe to call grpc_completion_queue_destroy. */ +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 */ +void grpc_completion_queue_destroy(grpc_completion_queue *cq); + +/* Create a call given a grpc_channel, in order to call 'method'. The request + is not sent until grpc_call_invoke is called. All completions are sent to + 'completion_queue'. */ +grpc_call *grpc_channel_create_call(grpc_channel *channel, const char *method, + const char *host, gpr_timespec deadline); + +/* Create a client channel */ +grpc_channel *grpc_channel_create(const char *target, + const grpc_channel_args *args); + +/* Close and destroy a grpc channel */ +void grpc_channel_destroy(grpc_channel *channel); + +/* THREAD-SAFETY for grpc_call + The following functions are thread-compatible for any given call: + grpc_call_add_metadata + grpc_call_invoke + grpc_call_start_write + grpc_call_writes_done + grpc_call_start_read + grpc_call_destroy + The function grpc_call_cancel is thread-safe, and can be called at any + point before grpc_call_destroy is called. */ + +/* Error handling for grpc_call + Most grpc_call functions return a grpc_error. If the error is not GRPC_OK + then the operation failed due to some unsatisfied precondition. + If a grpc_call fails, it's guaranteed that no change to the call state + has been made. */ + +/* Add a single metadata element to the call, to be sent upon invocation. + flags is a bit-field combination of the write flags defined above. + REQUIRES: grpc_call_start_invoke/grpc_call_accept have not been called on + this call. + Produces no events. */ +grpc_call_error grpc_call_add_metadata(grpc_call *call, grpc_metadata *metadata, + gpr_uint32 flags); + +/* Invoke the RPC. Starts sending metadata and request headers on the wire. + flags is a bit-field combination of the write flags defined above. + REQUIRES: Can be called at most once per call. + Can only be called on the client. + Produces a GRPC_INVOKE_ACCEPTED event with invoke_accepted_tag when the + call has been invoked (meaning bytes can start flowing to the wire). + Produces a GRPC_CLIENT_METADATA_READ event with metadata_read_tag when + the servers initial metadata has been read. + Produces a GRPC_FINISHED event with finished_tag when the call has been + completed (there may be other events for the call pending at this + time) */ +grpc_call_error grpc_call_start_invoke(grpc_call *call, + grpc_completion_queue *cq, + void *invoke_accepted_tag, + void *metadata_read_tag, + void *finished_tag, gpr_uint32 flags); + +/* Accept an incoming RPC, binding a completion queue to it. + To be called after adding metadata to the call, but before sending + messages. + flags is a bit-field combination of the write flags defined above. + REQUIRES: Can be called at most once per call. + Can only be called on the server. + Produces a GRPC_FINISHED event with finished_tag when the call has been + completed (there may be other events for the call pending at this + time) */ +grpc_call_error grpc_call_accept(grpc_call *call, grpc_completion_queue *cq, + void *finished_tag, gpr_uint32 flags); + +/* Called by clients to cancel an RPC on the server. + Can be called multiple times, from any thread. */ +grpc_call_error grpc_call_cancel(grpc_call *call); + +/* Queue a byte buffer for writing. + flags is a bit-field combination of the write flags defined above. + A write with byte_buffer null is allowed, and will not send any bytes on the + wire. If this is performed without GRPC_WRITE_BUFFER_HINT flag it provides + a mechanism to flush any previously buffered writes to outgoing flow control. + REQUIRES: No other writes are pending on the call. It is only safe to + start the next write after the corresponding write_accepted event + is received. + GRPC_INVOKE_ACCEPTED must have been received by the application + prior to calling this on the client. On the server, + grpc_call_accept must have been called successfully. + Produces a GRPC_WRITE_ACCEPTED event. */ +grpc_call_error grpc_call_start_write(grpc_call *call, + grpc_byte_buffer *byte_buffer, void *tag, + gpr_uint32 flags); + +/* Queue a status for writing. + REQUIRES: No other writes are pending on the call. + grpc_call_accept must have been called on the call prior to calling + this. + Only callable on the server. + Produces a GRPC_FINISH_ACCEPTED event when the status is sent. */ +grpc_call_error grpc_call_start_write_status(grpc_call *call, + grpc_status status, void *tag); + +/* No more messages to send. + REQUIRES: No other writes are pending on the call. + Only callable on the client. + Produces a GRPC_FINISH_ACCEPTED event when all bytes for the call have passed + outgoing flow control. */ +grpc_call_error grpc_call_writes_done(grpc_call *call, void *tag); + +/* Initiate a read on a call. Output event contains a byte buffer with the + result of the read. + REQUIRES: No other reads are pending on the call. It is only safe to start + the next read after the corresponding read event is received. + GRPC_INVOKE_ACCEPTED must have been received by the application + prior to calling this. + Produces a single GRPC_READ event. */ +grpc_call_error grpc_call_start_read(grpc_call *call, void *tag); + +/* Destroy a call. */ +void grpc_call_destroy(grpc_call *call); + +/* Request a call on a server. + Allows the server to create a single GRPC_SERVER_RPC_NEW event, with tag + tag_new. + If the call is subsequently cancelled, the cancellation will occur with tag + tag_cancel. + REQUIRES: Server must not have been shutdown. + NOTE: calling this is the only way to obtain GRPC_SERVER_RPC_NEW events. */ +grpc_call_error grpc_server_request_call(grpc_server *server, void *tag_new); + +/* Create a server */ +grpc_server *grpc_server_create(grpc_completion_queue *cq, + const grpc_channel_args *args); + +/* Add a http2 over tcp listener; returns 1 on success, 0 on failure + REQUIRES: server not started */ +int grpc_server_add_http2_port(grpc_server *server, const char *addr); + +/* Add a secure port to server; returns 1 on success, 0 on failure + REQUIRES: server not started */ +int grpc_server_add_secure_http2_port(grpc_server *server, const char *addr); + +/* Start a server - tells all listeners to start listening */ +void grpc_server_start(grpc_server *server); + +/* Begin shutting down a server. */ +void grpc_server_shutdown(grpc_server *server); + +/* Destroy a server */ +void grpc_server_destroy(grpc_server *server); + +#ifdef __cplusplus +} +#endif + +#endif /* __GRPC_GRPC_H__ */ |