mirror of https://github.com/grpc/grpc.git
Conflicts: src/core/surface/call.c src/core/transport/chttp2_transport.c src/core/transport/transport.hpull/1888/head
Craig Tiller
10 years ago
commit
27166a6f65
502 changed files with 26942 additions and 8389 deletions
@ -0,0 +1,147 @@ |
||||
gRPC Connectivity Semantics and API |
||||
=================================== |
||||
|
||||
This document describes the connectivity semantics for gRPC channels and the |
||||
corresponding impact on RPCs. We then discuss an API. |
||||
|
||||
States of Connectivity |
||||
---------------------- |
||||
|
||||
gRPC Channels provide the abstraction over which clients can communicate with |
||||
servers.The client-side channel object can be constructed using little more |
||||
than a DNS name. Channels encapsulate a range of functionality including name |
||||
resolution, establishing a TCP connection (with retries and backoff) and TLS |
||||
handshakes. Channels can also handle errors on established connections and |
||||
reconnect, or in the case of HTTP/2 GO_AWAY, re-resolve the name and reconnect. |
||||
|
||||
To hide the details of all this activity from the user of the gRPC API (i.e., |
||||
application code) while exposing meaningful information about the state of a |
||||
channel, we use a state machine with four states, defined below: |
||||
|
||||
CONNECTING: The channel is trying to establish a connection and is waiting to |
||||
make progress on one of the steps involved in name resolution, TCP connection |
||||
establishment or TLS handshake. This may be used as the initial state for channels upon |
||||
creation. |
||||
|
||||
READY: The channel has successfully established a connection all the way |
||||
through TLS handshake (or equivalent) and all subsequent attempt to communicate |
||||
have succeeded (or are pending without any known failure ). |
||||
|
||||
TRANSIENT_FAILURE: There has been some transient failure (such as a TCP 3-way |
||||
handshake timing out or a socket error). Channels in this state will eventually |
||||
switch to the CONNECTING state and try to establish a connection again. Since |
||||
retries are done with exponential backoff, channels that fail to connect will |
||||
start out spending very little time in this state but as the attempts fail |
||||
repeatedly, the channel will spend increasingly large amounts of time in this |
||||
state. For many non-fatal failures (e.g., TCP connection attempts timing out |
||||
because the server is not yet available), the channel may spend increasingly |
||||
large amounts of time in this state. |
||||
|
||||
IDLE: This is the state where the channel is not even trying to create a |
||||
connection because of a lack of new or pending RPCs. New channels MAY be created |
||||
in this state. Any attempt to start an RPC on the channel will push the channel |
||||
out of this state to connecting. When there has been no RPC activity on a channel |
||||
for a specified IDLE_TIMEOUT, i.e., no new or pending (active) RPCs for this |
||||
period, channels that are READY or CONNECTING switch to IDLE. Additionaly, |
||||
channels that receive a GOAWAY when there are no active or pending RPCs should |
||||
also switch to IDLE to avoid connection overload at servers that are attempting |
||||
to shed connections. We will use a default IDLE_TIMEOUT of 300 seconds (5 minutes). |
||||
|
||||
SHUTDOWN: This channel has started shutting down. Any new RPCs should fail |
||||
immediately. Pending RPCs may continue running till the application cancels them. |
||||
Channels may enter this state either because the application explicitly requested |
||||
a shutdown or if a non-recoverable error has happened during attempts to connect |
||||
communicate . (As of 6/12/2015, there are no known errors (while connecting or |
||||
communicating) that are classified as non-recoverable) |
||||
Channels that enter this state never leave this state. |
||||
|
||||
The following table lists the legal transitions from one state to another and |
||||
corresponding reasons. Empty cells denote disallowed transitions. |
||||
|
||||
<table style='border: 1px solid black'> |
||||
<tr> |
||||
<th>From/To</th> |
||||
<th>CONNECTING</th> |
||||
<th>READY</th> |
||||
<th>TRANSIENT_FAILURE</th> |
||||
<th>IDLE</th> |
||||
<th>SHUTDOWN</th> |
||||
</tr> |
||||
<tr> |
||||
<th>CONNECTING</th> |
||||
<td>Incremental progress during connection establishment</td> |
||||
<td>All steps needed to establish a connection succeeded</td> |
||||
<td>Any failure in any of the steps needed to establish connection</td> |
||||
<td>No RPC activity on channel for IDLE_TIMEOUT</td> |
||||
<td>Shutdown triggered by application.</td> |
||||
</tr> |
||||
<tr> |
||||
<th>READY</th> |
||||
<td></td> |
||||
<td>Incremental successful communication on established channel.</td> |
||||
<td>Any failure encountered while expecting successful communication on |
||||
established channel.</td> |
||||
<td>No RPC activity on channel for IDLE_TIMEOUT <br>OR<br>upon receiving a GOAWAY while there are no pending RPCs.</td> |
||||
<td>Shutdown triggered by application.</td> |
||||
</tr> |
||||
<tr> |
||||
<th>TRANSIENT_FAILURE</th> |
||||
<td>Wait time required to implement (exponential) backoff is over.</td> |
||||
<td></td> |
||||
<td></td> |
||||
<td></td> |
||||
<td>Shutdown triggered by application.</td> |
||||
</tr> |
||||
<tr> |
||||
<th>IDLE</th> |
||||
<td>Any new RPC activity on the channel</td> |
||||
<td></td> |
||||
<td></td> |
||||
<td></td> |
||||
<td>Shutdown triggered by application.</td> |
||||
</tr> |
||||
<tr> |
||||
<th>FATAL_FAILURE</th> |
||||
<td></td> |
||||
<td></td> |
||||
<td></td> |
||||
<td></td> |
||||
<td></td> |
||||
</tr> |
||||
</table> |
||||
|
||||
|
||||
Channel State API |
||||
----------------- |
||||
|
||||
All gRPC libraries will expose a channel-level API method to poll the current |
||||
state of a channel. In C++, this method is called GetCurrentState and returns |
||||
an enum for one of the four legal states. |
||||
|
||||
All libraries should also expose an API that enables the application (user of |
||||
the gRPC API) to be notified when the channel state changes. Since state |
||||
changes can be rapid and race with any such notification, the notification |
||||
should just inform the user that some state change has happened, leaving it to |
||||
the user to poll the channel for the current state. |
||||
|
||||
The synchronous version of this API is: |
||||
|
||||
```cpp |
||||
bool WaitForStateChange(gpr_timespec deadline, ChannelState source_state); |
||||
``` |
||||
|
||||
which returns true when the state changes to something other than the |
||||
source_state and false if the deadline expires. Asynchronous and futures based |
||||
APIs should have a corresponding method that allows the application to be |
||||
notified when the state of a channel changes. |
||||
|
||||
Note that a notification is delivered every time there is a transition from any |
||||
state to any *other* state. On the other hand the rules for legal state |
||||
transition, require a transition from CONNECTING to TRANSIENT_FAILURE and back |
||||
to CONNECTING for every recoverable failure, even if the corresponding |
||||
exponential backoff requires no wait before retry. The combined effect is that |
||||
the application may receive state change notifications that appear spurious. |
||||
e.g., an application waiting for state changes on a channel that is CONNECTING |
||||
may receive a state change notification but find the channel in the same |
||||
CONNECTING state on polling for current state because the channel may have |
||||
spent infinitesimally small amount of time in the TRANSIENT_FAILURE state. |
||||
@ -0,0 +1,72 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2015, 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 GRPCXX_CONFIG_PROTOBUF_H |
||||
#define GRPCXX_CONFIG_PROTOBUF_H |
||||
|
||||
#ifndef GRPC_CUSTOM_PROTOBUF_INT64 |
||||
#include <google/protobuf/stubs/common.h> |
||||
#define GRPC_CUSTOM_PROTOBUF_INT64 ::google::protobuf::int64 |
||||
#endif |
||||
|
||||
#ifndef GRPC_CUSTOM_MESSAGE |
||||
#include <google/protobuf/message.h> |
||||
#define GRPC_CUSTOM_MESSAGE ::google::protobuf::Message |
||||
#endif |
||||
|
||||
#ifndef GRPC_CUSTOM_ZEROCOPYOUTPUTSTREAM |
||||
#include <google/protobuf/io/coded_stream.h> |
||||
#include <google/protobuf/io/zero_copy_stream.h> |
||||
#define GRPC_CUSTOM_ZEROCOPYOUTPUTSTREAM \ |
||||
::google::protobuf::io::ZeroCopyOutputStream |
||||
#define GRPC_CUSTOM_ZEROCOPYINPUTSTREAM \ |
||||
::google::protobuf::io::ZeroCopyInputStream |
||||
#define GRPC_CUSTOM_CODEDINPUTSTREAM ::google::protobuf::io::CodedInputStream |
||||
#endif |
||||
|
||||
namespace grpc { |
||||
namespace protobuf { |
||||
|
||||
typedef GRPC_CUSTOM_MESSAGE Message; |
||||
typedef GRPC_CUSTOM_PROTOBUF_INT64 int64; |
||||
|
||||
namespace io { |
||||
typedef GRPC_CUSTOM_ZEROCOPYOUTPUTSTREAM ZeroCopyOutputStream; |
||||
typedef GRPC_CUSTOM_ZEROCOPYINPUTSTREAM ZeroCopyInputStream; |
||||
typedef GRPC_CUSTOM_CODEDINPUTSTREAM CodedInputStream; |
||||
} // namespace io
|
||||
|
||||
} // namespace protobuf
|
||||
} // namespace grpc
|
||||
|
||||
#endif // GRPCXX_CONFIG_PROTOBUF_H
|
||||
@ -0,0 +1,76 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2015, 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_INTERNAL_CPP_PROTO_PROTO_UTILS_H |
||||
#define GRPC_INTERNAL_CPP_PROTO_PROTO_UTILS_H |
||||
|
||||
#include <type_traits> |
||||
|
||||
#include <grpc/grpc.h> |
||||
#include <grpc++/impl/serialization_traits.h> |
||||
#include <grpc++/config_protobuf.h> |
||||
#include <grpc++/status.h> |
||||
|
||||
namespace grpc { |
||||
|
||||
// Serialize the msg into a buffer created inside the function. The caller
|
||||
// should destroy the returned buffer when done with it. If serialization fails,
|
||||
// false is returned and buffer is left unchanged.
|
||||
Status SerializeProto(const grpc::protobuf::Message& msg, |
||||
grpc_byte_buffer** buffer); |
||||
|
||||
// The caller keeps ownership of buffer and msg.
|
||||
Status DeserializeProto(grpc_byte_buffer* buffer, grpc::protobuf::Message* msg, |
||||
int max_message_size); |
||||
|
||||
template <class T> |
||||
class SerializationTraits<T, typename std::enable_if<std::is_base_of< |
||||
grpc::protobuf::Message, T>::value>::type> { |
||||
public: |
||||
static Status Serialize(const grpc::protobuf::Message& msg, |
||||
grpc_byte_buffer** buffer, bool* own_buffer) { |
||||
*own_buffer = true; |
||||
return SerializeProto(msg, buffer); |
||||
} |
||||
static Status Deserialize(grpc_byte_buffer* buffer, |
||||
grpc::protobuf::Message* msg, |
||||
int max_message_size) { |
||||
auto status = DeserializeProto(buffer, msg, max_message_size); |
||||
grpc_byte_buffer_destroy(buffer); |
||||
return status; |
||||
} |
||||
}; |
||||
|
||||
} // namespace grpc
|
||||
|
||||
#endif // GRPC_INTERNAL_CPP_PROTO_PROTO_UTILS_H
|
||||
@ -0,0 +1,68 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2015, 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 GRPCXX_IMPL_SERIALIZATION_TRAITS_H |
||||
#define GRPCXX_IMPL_SERIALIZATION_TRAITS_H |
||||
|
||||
namespace grpc { |
||||
|
||||
/// Defines how to serialize and deserialize some type.
|
||||
///
|
||||
/// Used for hooking different message serialization API's into GRPC.
|
||||
/// Each SerializationTraits implementation must provide the following
|
||||
/// functions:
|
||||
/// static Status Serialize(const Message& msg,
|
||||
/// grpc_byte_buffer** buffer,
|
||||
// bool* own_buffer);
|
||||
/// static Status Deserialize(grpc_byte_buffer* buffer,
|
||||
/// Message* msg,
|
||||
/// int max_message_size);
|
||||
///
|
||||
/// Serialize is required to convert message to a grpc_byte_buffer, and
|
||||
/// to store a pointer to that byte buffer at *buffer. *own_buffer should
|
||||
/// be set to true if the caller owns said byte buffer, or false if
|
||||
/// ownership is retained elsewhere.
|
||||
///
|
||||
/// Deserialize is required to convert buffer into the message stored at
|
||||
/// msg. max_message_size is passed in as a bound on the maximum number of
|
||||
/// message bytes Deserialize should accept.
|
||||
///
|
||||
/// Both functions return a Status, allowing them to explain what went
|
||||
/// wrong if required.
|
||||
template <class Message, |
||||
class UnusedButHereForPartialTemplateSpecialization = void> |
||||
class SerializationTraits; |
||||
|
||||
} // namespace grpc
|
||||
|
||||
#endif // GRPCXX_IMPL_SERIALIZATION_TRAITS_H
|
||||
@ -0,0 +1,61 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2015, 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_SUPPORT_STRING_UTIL_H |
||||
#define GRPC_SUPPORT_STRING_UTIL_H |
||||
|
||||
#ifdef __cplusplus |
||||
extern "C" { |
||||
#endif |
||||
|
||||
/* String utility functions */ |
||||
|
||||
/* Returns a copy of src that can be passed to gpr_free().
|
||||
If allocation fails or if src is NULL, returns NULL. */ |
||||
char *gpr_strdup(const char *src); |
||||
|
||||
/* printf to a newly-allocated string. The set of supported formats may vary
|
||||
between platforms. |
||||
|
||||
On success, returns the number of bytes printed (excluding the final '\0'), |
||||
and *strp points to a string which must later be destroyed with gpr_free(). |
||||
|
||||
On error, returns -1 and sets *strp to NULL. If the format string is bad, |
||||
the result is undefined. */ |
||||
int gpr_asprintf(char **strp, const char *format, ...); |
||||
|
||||
#ifdef __cplusplus |
||||
} |
||||
#endif |
||||
|
||||
#endif /* GRPC_SUPPORT_STRING_UTIL_H */ |
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue