diff --git a/BUILD b/BUILD index 72a496dce1a395a1f624fd779b0e3acc657caf70..26cdc7f640645adb3c7876cafb457728d2cdc423 100644 --- a/BUILD +++ b/BUILD @@ -729,6 +729,7 @@ cc_library( "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", @@ -819,6 +820,7 @@ cc_library( "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", diff --git a/Makefile b/Makefile index 1c2fca3154d42f6a124152448ff571e2b90c297f..7396818802961498ae2b3dace9280d8af7e03fed 100644 --- a/Makefile +++ b/Makefile @@ -4593,6 +4593,7 @@ PUBLIC_HEADERS_CXX += \ include/grpc++/create_channel.h \ include/grpc++/generic/async_generic_service.h \ include/grpc++/generic/generic_stub.h \ + include/grpc++/grpc++.h \ include/grpc++/impl/call.h \ include/grpc++/impl/client_unary_call.h \ include/grpc++/impl/grpc_library.h \ @@ -4838,6 +4839,7 @@ PUBLIC_HEADERS_CXX += \ include/grpc++/create_channel.h \ include/grpc++/generic/async_generic_service.h \ include/grpc++/generic/generic_stub.h \ + include/grpc++/grpc++.h \ include/grpc++/impl/call.h \ include/grpc++/impl/client_unary_call.h \ include/grpc++/impl/grpc_library.h \ diff --git a/build.json b/build.json index 1e00771ee330079a93e423ad8c6f27df77ef3a9f..8a51249cd092006f0cc3c0ed70cf19c42eabd671 100644 --- a/build.json +++ b/build.json @@ -38,6 +38,7 @@ "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", diff --git a/examples/cpp/helloworld/greeter_async_client.cc b/examples/cpp/helloworld/greeter_async_client.cc index 1d2dad052ede1c152660a5e1ab760bf27707a60b..d464629ec5327a5505047131a17306819a739e6c 100644 --- a/examples/cpp/helloworld/greeter_async_client.cc +++ b/examples/cpp/helloworld/greeter_async_client.cc @@ -75,7 +75,7 @@ class GreeterClient { ClientContext context; // The producer-consumer queue we use to communicate asynchronously with the - // gRPC runtmie. + // gRPC runtime. CompletionQueue cq; // Storage for the status of the RPC upon completion. diff --git a/include/grpc++/channel.h b/include/grpc++/channel.h index 0ad3cc42522af0077bd16bc263eb4231980cb7af..60c816d58ac942a210cbb5291002afea7744e7b3 100644 --- a/include/grpc++/channel.h +++ b/include/grpc++/channel.h @@ -72,12 +72,12 @@ class Channel GRPC_FINAL : public GrpcLibrary, public: ~Channel(); - /// Get the current channel state. If the channel is in IDLE and try_to_connect - /// is set to true, try to connect. + /// Get the current channel state. If the channel is in IDLE and + /// \a try_to_connect is set to true, try to connect. grpc_connectivity_state GetState(bool try_to_connect); - /// Return the tag on cq when the channel state is changed or deadline expires. - /// GetState needs to called to get the current state. + /// Return the \a tag on \a cq when the channel state is changed or \a + /// deadline expires. \a GetState needs to called to get the current state. template <typename T> void NotifyOnStateChange(grpc_connectivity_state last_observed, T deadline, CompletionQueue* cq, void* tag) { @@ -85,8 +85,8 @@ class Channel GRPC_FINAL : public GrpcLibrary, NotifyOnStateChangeImpl(last_observed, deadline_tp.raw_time(), cq, tag); } - /// Blocking wait for channel state change or deadline expiration. - /// GetState needs to called to get the current state. + /// Blocking wait for channel state change or \a deadline expiration. + /// \a GetState needs to called to get the current state. template <typename T> bool WaitForStateChange(grpc_connectivity_state last_observed, T deadline) { TimePoint<T> deadline_tp(deadline); diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h index d8c885dd9d1f8033024dd387bb8e5cde5b05fc71..9c6ea7ce14b5fb19598632e67d5847a94edd83b6 100644 --- a/include/grpc++/completion_queue.h +++ b/include/grpc++/completion_queue.h @@ -77,8 +77,8 @@ class Server; class ServerBuilder; class ServerContext; -// This class is a thin wrapper around \a grpc_completion_queue (see -// \a src/core/surface/completion_queue.h). +/// A thin wrapper around \a grpc_completion_queue (see / \a +/// src/core/surface/completion_queue.h). class CompletionQueue : public GrpcLibrary { public: /// Default constructor. Implicitly creates a \a grpc_completion_queue @@ -86,7 +86,7 @@ class CompletionQueue : public GrpcLibrary { CompletionQueue(); /// Wrap \a take, taking ownership of the instance. - /// + /// /// \param take The completion queue instance to wrap. Ownership is taken. explicit CompletionQueue(grpc_completion_queue* take); diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h new file mode 100644 index 0000000000000000000000000000000000000000..af87b9ea5548719d8e12d67f35ede0da72641c18 --- /dev/null +++ b/include/grpc++/grpc++.h @@ -0,0 +1,64 @@ +/* + * + * 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. + * + */ + +/// \mainpage gRPC C++ API +/// +/// The gRPC C++ API mainly consists of the following classes: +/// - grpc::Channel, which represents the connection to an endpoint. See [the +/// gRPC Concepts page](http://www.grpc.io/docs/guides/concepts.html) for more +/// details. Channels are created by the factory function grpc::CreateChannel. +/// - grpc::CompletionQueue, the producer-consumer queue used for all +/// asynchronous communication with the gRPC runtime. +/// - grpc::ClientContext and grpc::ServerContext, where optional configuration +/// for an RPC can be set, such as setting custom metadata to be conveyed to the +/// peer, compression settings, authentication, etc. +/// - grpc::Server, representing a gRPC server, created by grpc::ServerBuilder. +/// +/// Refer to the [examples](https://github.com/grpc/grpc/blob/master/examples/cpp) +/// for code putting these pieces into play. + +#ifndef GRPCXX_GRPCXX_H +#define GRPCXX_GRPCXX_H + +#include <grpc/grpc.h> + +#include <grpc++/channel.h> +#include <grpc++/client_context.h> +#include <grpc++/completion_queue.h> +#include <grpc++/create_channel.h> +#include <grpc++/server.h> +#include <grpc++/server_builder.h> +#include <grpc++/server_context.h> + +#endif // GRPCXX_GRPCXX_H + diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h index a75f35631270a80032101dc2e97938395c60bea6..47f3df6605ae41b2fd908e461eb2bedcaf284124 100644 --- a/include/grpc/grpc.h +++ b/include/grpc/grpc.h @@ -47,11 +47,9 @@ extern "C" { /*! \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. + * 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 diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 96708c062272e86b956ac13a4f54803546c92245..f120f77c79a50b22605db1a531718e708a4ad938 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -766,6 +766,7 @@ include/grpc++/completion_queue.h \ include/grpc++/create_channel.h \ include/grpc++/generic/async_generic_service.h \ include/grpc++/generic/generic_stub.h \ +include/grpc++/grpc++.h \ include/grpc++/impl/call.h \ include/grpc++/impl/client_unary_call.h \ include/grpc++/impl/grpc_library.h \ diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index 185d24720ceac7cb11335e4422fbb174b8fb25a4..7eabe52ecb332d12767ba10b3f4eefbd7e77f0bf 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -766,6 +766,7 @@ include/grpc++/completion_queue.h \ include/grpc++/create_channel.h \ include/grpc++/generic/async_generic_service.h \ include/grpc++/generic/generic_stub.h \ +include/grpc++/grpc++.h \ include/grpc++/impl/call.h \ include/grpc++/impl/client_unary_call.h \ include/grpc++/impl/grpc_library.h \ diff --git a/tools/run_tests/sources_and_headers.json b/tools/run_tests/sources_and_headers.json index 939261da650e8c26f235cc7133e6737316477301..cd95ce4e82fd0560b041fb48a22851654e6b2ac7 100644 --- a/tools/run_tests/sources_and_headers.json +++ b/tools/run_tests/sources_and_headers.json @@ -13094,6 +13094,7 @@ "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", @@ -13146,6 +13147,7 @@ "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", @@ -13276,6 +13278,7 @@ "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", @@ -13325,6 +13328,7 @@ "include/grpc++/create_channel.h", "include/grpc++/generic/async_generic_service.h", "include/grpc++/generic/generic_stub.h", + "include/grpc++/grpc++.h", "include/grpc++/impl/call.h", "include/grpc++/impl/client_unary_call.h", "include/grpc++/impl/grpc_library.h", diff --git a/vsprojects/grpc++/grpc++.vcxproj b/vsprojects/grpc++/grpc++.vcxproj index 5f8b7d8f4ca7e63d4036584dbdc092c51606f324..ac91f62d2a0624a227e7d331c1d71b156e93549f 100644 --- a/vsprojects/grpc++/grpc++.vcxproj +++ b/vsprojects/grpc++/grpc++.vcxproj @@ -219,6 +219,7 @@ <ClInclude Include="..\..\include\grpc++\create_channel.h" /> <ClInclude Include="..\..\include\grpc++\generic\async_generic_service.h" /> <ClInclude Include="..\..\include\grpc++\generic\generic_stub.h" /> + <ClInclude Include="..\..\include\grpc++\grpc++.h" /> <ClInclude Include="..\..\include\grpc++\impl\call.h" /> <ClInclude Include="..\..\include\grpc++\impl\client_unary_call.h" /> <ClInclude Include="..\..\include\grpc++\impl\grpc_library.h" /> diff --git a/vsprojects/grpc++/grpc++.vcxproj.filters b/vsprojects/grpc++/grpc++.vcxproj.filters index 38b5e14e0b52a37baa2abe0aebfb5ac0a95642ad..ff275999d757c0f7b181c43d807c8fe09a92e133 100644 --- a/vsprojects/grpc++/grpc++.vcxproj.filters +++ b/vsprojects/grpc++/grpc++.vcxproj.filters @@ -117,6 +117,9 @@ <ClInclude Include="..\..\include\grpc++\generic\generic_stub.h"> <Filter>include\grpc++\generic</Filter> </ClInclude> + <ClInclude Include="..\..\include\grpc++\grpc++.h"> + <Filter>include\grpc++</Filter> + </ClInclude> <ClInclude Include="..\..\include\grpc++\impl\call.h"> <Filter>include\grpc++\impl</Filter> </ClInclude> diff --git a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj index 68154c67ec7f838737296b2c92e8aaba75697676..9365a247d43b114c9da649ad6ed03708d3857db9 100644 --- a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj +++ b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj @@ -219,6 +219,7 @@ <ClInclude Include="..\..\include\grpc++\create_channel.h" /> <ClInclude Include="..\..\include\grpc++\generic\async_generic_service.h" /> <ClInclude Include="..\..\include\grpc++\generic\generic_stub.h" /> + <ClInclude Include="..\..\include\grpc++\grpc++.h" /> <ClInclude Include="..\..\include\grpc++\impl\call.h" /> <ClInclude Include="..\..\include\grpc++\impl\client_unary_call.h" /> <ClInclude Include="..\..\include\grpc++\impl\grpc_library.h" /> diff --git a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters index 52582d3aed67c8bef08e75ffac1ec27d493658e7..925ee9c81aa75f865ab1dd571489ec0464e119fa 100644 --- a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters +++ b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters @@ -102,6 +102,9 @@ <ClInclude Include="..\..\include\grpc++\generic\generic_stub.h"> <Filter>include\grpc++\generic</Filter> </ClInclude> + <ClInclude Include="..\..\include\grpc++\grpc++.h"> + <Filter>include\grpc++</Filter> + </ClInclude> <ClInclude Include="..\..\include\grpc++\impl\call.h"> <Filter>include\grpc++\impl</Filter> </ClInclude>