diff --git a/include/grpc++/auth_context.h b/include/grpc++/auth_context.h index 7dced90ce50..721d5b9927c 100644 --- a/include/grpc++/auth_context.h +++ b/include/grpc++/auth_context.h @@ -72,20 +72,26 @@ class AuthPropertyIterator const char* name_; }; +/// Class encapsulating the Authentication Information. +/// +/// It includes the secure identity of the peer, the type of secure transport +/// used as well as any other properties required by the authorization layer. class AuthContext { public: virtual ~AuthContext() {} - // A peer identity, in general is one or more properties (in which case they - // have the same name). + /// A peer identity. + /// + /// It is, in general, comprised of one or more properties (in which case they + /// have the same name). virtual std::vector GetPeerIdentity() const = 0; virtual grpc::string GetPeerIdentityPropertyName() const = 0; - // Returns all the property values with the given name. + /// Returns all the property values with the given name. virtual std::vector FindPropertyValues( const grpc::string& name) const = 0; - // Iteration over all the properties. + /// Iteration over all the properties. virtual AuthPropertyIterator begin() const = 0; virtual AuthPropertyIterator end() const = 0; }; diff --git a/include/grpc++/client_context.h b/include/grpc++/client_context.h index f40beb64ba1..a8aacc00451 100644 --- a/include/grpc++/client_context.h +++ b/include/grpc++/client_context.h @@ -206,21 +206,32 @@ class ClientContext { } #ifndef GRPC_CXX0X_NO_CHRONO + /// Return the deadline for the client call. std::chrono::system_clock::time_point deadline() { return Timespec2Timepoint(deadline_); } #endif // !GRPC_CXX0X_NO_CHRONO - /// XXX: what's raw about this? is it absolute time? + /// Return a \a gpr_timespec representation of the client call's deadline. gpr_timespec raw_deadline() { return deadline_; } - /// XXX what's an authority? + /// Set the per call authority header (see + /// https://tools.ietf.org/html/rfc7540#section-8.1.2.3). void set_authority(const grpc::string& authority) { authority_ = authority; } - /// XXX: what's an auth context? what is it used for? + /// Return the authentication context for this client call. + /// + /// \see grpc::AuthContext. std::shared_ptr auth_context() const; - /// Set credentials for the rpc. XXX: how do credentials work? + /// Set credentials for the client call. + /// + /// A credentials object encapsulates all the state needed by a client to + /// authenticate with a server and make various assertions, e.g., about the + /// client’s identity, role, or whether it is authorized to make a particular + /// call. + /// + /// \see https://github.com/grpc/grpc-common/blob/master/grpc-auth-support.md void set_credentials(const std::shared_ptr& creds) { creds_ = creds; } diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h index 0f7bdee80e3..a87f2eaef8c 100644 --- a/include/grpc++/completion_queue.h +++ b/include/grpc++/completion_queue.h @@ -32,12 +32,8 @@ */ -/// A completion queue implements a producer-consumer queue, with two main -/// methods: -/// -/// - Next -/// - AsyncNext XXX -/// +/// A completion queue implements a concurrent producer-consumer queue, with two +/// main methods, \a Next and \a AsyncNext. #ifndef GRPCXX_COMPLETION_QUEUE_H #define GRPCXX_COMPLETION_QUEUE_H @@ -81,35 +77,67 @@ class Server; class ServerBuilder; class ServerContext; -// grpc_completion_queue wrapper class +// This class is 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 + /// instance. 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); + + /// Destructor. Destroys the owned wrapped completion queue / instance. ~CompletionQueue() GRPC_OVERRIDE; - // Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT + /// Tri-state return for AsyncNext: SHUTDOWN, GOT_EVENT, TIMEOUT. enum NextStatus { SHUTDOWN, GOT_EVENT, TIMEOUT }; - // Nonblocking (until deadline) read from queue. - // Cannot rely on result of tag or ok if return is TIMEOUT + /// Read from the queue, blocking up to \a deadline (or the queue's shutdown). + /// Both \a tag and \a ok are updated upon success (if an event is available + /// within the \a deadline). A \a tag points to an arbitrary location usually + /// employed to uniquely identify an event. + /// + /// \param tag[out] Upon sucess, updated to point to the event's tag. + /// \param ok[out] Upon sucess, true if read a regular event, false otherwise. + /// \param deadline[in] How long to block in wait for an event. + /// + /// \return The type of event read. template NextStatus AsyncNext(void** tag, bool* ok, const T& deadline) { TimePoint deadline_tp(deadline); return AsyncNextInternal(tag, ok, deadline_tp.raw_time()); } - // Blocking read from queue. - // Returns false if the queue is ready for destruction, true if event + /// Read from the queue, blocking until an event is available or the queue is + /// shutting down. + /// + /// \param tag[out] Updated to point to the read event's tag. + /// \param ok[out] true if read a regular event, false otherwise. + /// + /// \return true if read a regular event, false if the queue is shutting down. bool Next(void** tag, bool* ok) { return (AsyncNextInternal(tag, ok, gpr_inf_future(GPR_CLOCK_REALTIME)) != SHUTDOWN); } - // Shutdown has to be called, and the CompletionQueue can only be - // destructed when false is returned from Next(). + /// Request the shutdown of the queue. + /// + /// \warning This method must be called at some point. Once invoked, \a Next + /// will start to return false and \a AsyncNext will return \a + /// NextStatus::SHUTDOWN. Only once either one of these methods does that + /// (that is, once the queue has been \em drained) can an instance of this + /// class be destroyed. void Shutdown(); + /// Returns a \em raw pointer to the underlying \a grpc_completion_queue + /// instance. + /// + /// \warning Remember that the returned instance is owned. No transfer of + /// owership is performed. grpc_completion_queue* cq() { return cq_; } private: @@ -147,27 +175,29 @@ class CompletionQueue : public GrpcLibrary { NextStatus AsyncNextInternal(void** tag, bool* ok, gpr_timespec deadline); - // Wraps grpc_completion_queue_pluck. - // Cannot be mixed with calls to Next(). + /// Wraps \a grpc_completion_queue_pluck. + /// \warning Must not be mixed with calls to \a Next. bool Pluck(CompletionQueueTag* tag); - // Does a single polling pluck on tag + /// Performs a single polling pluck on \a tag. void TryPluck(CompletionQueueTag* tag); grpc_completion_queue* cq_; // owned }; +/// An interface allowing implementors to process and filter event tags. class CompletionQueueTag { public: virtual ~CompletionQueueTag() {} - // Called prior to returning from Next(), return value - // is the status of the operation (return status is the default thing - // to do) - // If this function returns false, the tag is dropped and not returned - // from the completion queue + // Called prior to returning from Next(), return value is the status of the + // operation (return status is the default thing to do). If this function + // returns false, the tag is dropped and not returned from the completion + // queue virtual bool FinalizeResult(void** tag, bool* status) = 0; }; +/// A specific type of completion queue used by the processing of notifications +/// by servers. class ServerCompletionQueue : public CompletionQueue { private: friend class ServerBuilder; diff --git a/include/grpc++/server.h b/include/grpc++/server.h index a2bc097c7f7..e1c6f54fccd 100644 --- a/include/grpc++/server.h +++ b/include/grpc++/server.h @@ -44,6 +44,10 @@ #include #include +/// The \a Server class models a gRPC server. +/// +/// Servers are configured and started via \a grpc::ServerBuilder. + struct grpc_server; namespace grpc { @@ -57,24 +61,27 @@ class ServerAsyncStreamingInterface; class ServerCredentials; class ThreadPoolInterface; -// Currently it only supports handling rpcs in a single thread. class Server GRPC_FINAL : public GrpcLibrary, private CallHook { public: ~Server(); - // Shutdown the server, block until all rpc processing finishes. - // Forcefully terminate pending calls after deadline expires. + /// Shutdown the server, blocking until all rpc processing finishes. + /// Forcefully terminate pending calls after \a deadline expires. + /// + /// \param deadline How long to wait until pending rpcs are forcefully + /// terminated. template void Shutdown(const T& deadline) { ShutdownInternal(TimePoint(deadline).raw_time()); } - // Shutdown the server, waiting for all rpc processing to finish. + /// Shutdown the server, waiting for all rpc processing to finish. void Shutdown() { ShutdownInternal(gpr_inf_future(GPR_CLOCK_MONOTONIC)); } - // Block waiting for all work to complete (the server must either - // be shutting down or some other thread must call Shutdown for this - // function to ever return) + /// Block waiting for all work to complete. + /// + /// \warning The server must be either shutting down or some other thread must + /// call \a Shutdown for this function to ever return. void Wait(); private: @@ -86,22 +93,53 @@ class Server GRPC_FINAL : public GrpcLibrary, private CallHook { class AsyncRequest; class ShutdownRequest; - // ServerBuilder use only + /// Server constructors. To be used by \a ServerBuilder only. + /// + /// \param thread_pool The threadpool instance to use for call processing. + /// \param thread_pool_owned Does the server own the \a thread_pool instance? + /// \param max_message_size Maximum message length that the channel can + /// receive. Server(ThreadPoolInterface* thread_pool, bool thread_pool_owned, int max_message_size); - // Register a service. This call does not take ownership of the service. - // The service must exist for the lifetime of the Server instance. + + /// Register a service. This call does not take ownership of the service. + /// The service must exist for the lifetime of the Server instance. bool RegisterService(const grpc::string* host, RpcService* service); + + /// Register an asynchronous service. This call does not take ownership of the + /// service. The service must exist for the lifetime of the Server instance. bool RegisterAsyncService(const grpc::string* host, AsynchronousService* service); + + /// Register a generic service. This call does not take ownership of the + /// service. The service must exist for the lifetime of the Server instance. void RegisterAsyncGenericService(AsyncGenericService* service); - // Add a listening port. Can be called multiple times. + + /// Tries to bind \a server to the given \a addr. + /// + /// It can be invoked multiple times. + /// + /// \param addr The address to try to bind to the server (eg, localhost:1234, + /// 192.168.1.1:31416, [::1]:27182, etc.). + /// \params creds The credentials associated with the server. + /// + /// \return bound port number on sucess, 0 on failure. + /// + /// \warning It's an error to call this method on an already started server. + // TODO(dgq): the "port" part seems to be a misnomer. int AddListeningPort(const grpc::string& addr, ServerCredentials* creds); - // Start the server. + + /// Start the server. + /// + /// \return true on a successful shutdown. bool Start(); void HandleQueueClosed(); + + /// Process one or more incoming calls. void RunRpc(); + + /// Schedule \a RunRpc to run in the threadpool. void ScheduleCallback(); void PerformOpsOnCall(CallOpSetInterface* ops, Call* call) GRPC_OVERRIDE; diff --git a/include/grpc++/server_credentials.h b/include/grpc++/server_credentials.h index 11acd67e8ad..865b44c54b6 100644 --- a/include/grpc++/server_credentials.h +++ b/include/grpc++/server_credentials.h @@ -11,7 +11,7 @@ * 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 + a * 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 @@ -44,7 +44,7 @@ struct grpc_server; namespace grpc { class Server; -// grpc_server_credentials wrapper class. +// Wrapper around \a grpc_server_credentials, a way to authenticate a server. class ServerCredentials { public: virtual ~ServerCredentials(); @@ -52,11 +52,16 @@ class ServerCredentials { private: friend class ::grpc::Server; + /// Tries to bind \a server to the given \a addr (eg, localhost:1234, + /// 192.168.1.1:31416, [::1]:27182, etc.) + /// + /// \return bound port number on sucess, 0 on failure. + // TODO(dgq): the "port" part seems to be a misnomer. virtual int AddPortToServer(const grpc::string& addr, grpc_server* server) = 0; }; -// Options to create ServerCredentials with SSL +/// Options to create ServerCredentials with SSL struct SslServerCredentialsOptions { SslServerCredentialsOptions() : force_client_auth(false) {} @@ -69,10 +74,11 @@ struct SslServerCredentialsOptions { bool force_client_auth; }; -// Builds SSL ServerCredentials given SSL specific options +/// Builds SSL ServerCredentials given SSL specific options std::shared_ptr SslServerCredentials( const SslServerCredentialsOptions& options); +/// Builds insecure server credentials. std::shared_ptr InsecureServerCredentials(); } // namespace grpc