Repository: mesos Updated Branches: refs/heads/master 7a737ce22 -> cd6480bf9
MESOS-2967: Convert comments in libprocess Socket to Doxygen format. Doxygen-ification of comments in libprocess socket.hpp and network.hpp. Review: https://reviews.apache.org/r/36141 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/cd6480bf Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/cd6480bf Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/cd6480bf Branch: refs/heads/master Commit: cd6480bf9c1cee8fae9c246623a465d69f9f6b20 Parents: 7a737ce Author: Joseph Wu <[email protected]> Authored: Mon Jul 6 13:56:11 2015 -0700 Committer: Benjamin Hindman <[email protected]> Committed: Mon Jul 6 14:30:32 2015 -0700 ---------------------------------------------------------------------- 3rdparty/libprocess/include/process/network.hpp | 27 ++-- 3rdparty/libprocess/include/process/socket.hpp | 144 +++++++++++++------ 2 files changed, 120 insertions(+), 51 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/cd6480bf/3rdparty/libprocess/include/process/network.hpp ---------------------------------------------------------------------- diff --git a/3rdparty/libprocess/include/process/network.hpp b/3rdparty/libprocess/include/process/network.hpp index f3f9955..f4192e0 100644 --- a/3rdparty/libprocess/include/process/network.hpp +++ b/3rdparty/libprocess/include/process/network.hpp @@ -9,9 +9,12 @@ namespace process { namespace network { -// Returns a socket file descriptor for the specified options. Note -// that on OS X, the returned socket will have the SO_NOSIGPIPE option -// set. +/** + * Returns a socket file descriptor for the specified options. + * + * **NOTE:** on OS X, the returned socket will have the SO_NOSIGPIPE + * option set. + */ inline Try<int> socket(int family, int type, int protocol) { int s; @@ -77,9 +80,12 @@ inline Try<int> connect(int s, const Address& address) } -// Returns the Address with the assigned ip and assigned port. -// Returns an error if the getsockname system call fails or the -// family type is not supported. +/** + * Returns the `Address` with the assigned ip and assigned port. + * + * @return An `Address` or an error if the `getsockname` system call + * fails or the family type is not supported. + */ inline Try<Address> address(int s) { struct sockaddr_storage storage; @@ -93,9 +99,12 @@ inline Try<Address> address(int s) } -// Returns the peer's Address for the accepted or connected socket. -// Returns an error if the getpeername system call fails or the -// family type is not supported. +/** + * Returns the peer's `Address` for the accepted or connected socket. + * + * @return An `Address` or an error if the `getpeername` system call + * fails or the family type is not supported. + */ inline Try<Address> peer(int s) { struct sockaddr_storage storage; http://git-wip-us.apache.org/repos/asf/mesos/blob/cd6480bf/3rdparty/libprocess/include/process/socket.hpp ---------------------------------------------------------------------- diff --git a/3rdparty/libprocess/include/process/socket.hpp b/3rdparty/libprocess/include/process/socket.hpp index d79d2e4..4d95183 100644 --- a/3rdparty/libprocess/include/process/socket.hpp +++ b/3rdparty/libprocess/include/process/socket.hpp @@ -14,14 +14,22 @@ namespace process { namespace network { -// An abstraction around a socket (file descriptor) that provides -// reference counting such that the socket is only closed (and thus, -// has the possiblity of being reused) after there are no more -// references. +/** + * An abstraction around a socket (file descriptor). + * + * Provides reference counting such that the socket is only closed + * (and thus, has the possiblity of being reused) after there are no + * more references. + */ class Socket { public: - // Available kinds of implementations. + /** + * Available kinds of implementations. + * + * @see process::network::PollSocketImpl + * @see process::network::LibeventSSLSocketImpl + */ enum Kind { POLL, #ifdef USE_SSL_SOCKET @@ -29,22 +37,46 @@ public: #endif }; - // Returns an instance of a Socket using the specified kind of - // implementation and potentially wrapping the specified file - // descriptor. + /** + * Returns an instance of a `Socket` using the specified kind of + * implementation. + * + * @param kind Optional. The desired `Socket` implementation. + * @param s Optional. The file descriptor to wrap with the `Socket`. + * + * @return An instance of a `Socket`. + */ static Try<Socket> create(Kind kind = DEFAULT_KIND(), int s = -1); - // Returns the default kind of implementation of Socket. + /** + * Returns the default `Kind` of implementation of `Socket`. + * + * @see process::network::Socket::Kind + */ static const Kind& DEFAULT_KIND(); - // The kind representing the underlying implementation. + /** + * Returns the kind representing the underlying implementation + * of the `Socket` instance. + * + * @see process::network::Socket::Kind + */ Kind kind() const { return impl->kind(); } - // Each socket is a reference counted, shared by default, concurrent - // object. However, since we want to support multiple - // implementations we use the Pimpl pattern (often called the - // compilation firewall) rather than forcing each Socket - // implementation to do this themselves. + /** + * Interface for a `Socket`. + * + * Each socket is: + * - reference counted, + * - shared by default, + * - and a concurrent object. + * + * Multiple implementations are supported via the Pimpl pattern, + * rather than forcing each Socket implementation to do this themselves. + * + * @see process::network::Socket + * @see [Pimpl pattern](https://en.wikipedia.org/wiki/Opaque_pointer) + */ class Impl : public std::enable_shared_from_this<Impl> { public: @@ -58,17 +90,32 @@ public: } } + /** + * Returns the file descriptor wrapped by the `Socket`. + */ int get() const { return s; } - // Interface functions implemented by this base class. + /** + * @copydoc network::address + */ Try<Address> address() const; + + /** + * @copydoc network::peer + */ Try<Address> peer() const; + + /** + * Assigns the specified address to the `Socket`. + * + * @return The assigned `Address` or an error if the bind system + * call fails. + */ Try<Address> bind(const Address& address); - // Socket::Impl interface. virtual Try<Nothing> listen(int backlog) = 0; virtual Future<Socket> accept() = 0; virtual Future<Nothing> connect(const Address& address) = 0; @@ -76,27 +123,32 @@ public: virtual Future<size_t> send(const char* data, size_t size) = 0; virtual Future<size_t> sendfile(int fd, off_t offset, size_t size) = 0; - // An overload of 'recv', receives data based on the specified - // 'size' parameter: - // - // Value of 'size' | Semantics - // --------------------|----------------- - // 0 | Returns an empty string. - // -1 | Receives until EOF. - // N | Returns a string of size N. - // 'None' | Returns a string of the available data. - // - // That is, if 'None' is specified than whenever data becomes - // available on the socket that much data will be returned. - // + /** + * An overload of `recv`, which receives data based on the specified + * 'size' parameter. + * + * @param size + * Value | Semantics + * :-------:|----------- + * 0 | Returns an empty string. + * -1 | Receives until EOF. + * N | Returns a string of size N. + * 'None' | Returns a string of the available data. + * If 'None' is specified, whenever data becomes available on the + * socket, that much data will be returned. + */ // TODO(benh): Consider returning Owned<std::string> or // Shared<std::string>, the latter enabling reuse of a pool of // preallocated strings/buffers. virtual Future<std::string> recv(const Option<ssize_t>& size = None()); - // An overload of 'send', sends all of the specified data unless - // sending fails in which case a failure is returned. - // + /** + * An overload of `send`, which sends all of the specified data. + * + * @param data The specified data to send. + * + * @return Nothing or an error in case the sending fails. + */ // TODO(benh): Consider taking Shared<std::string>, the latter // enabling reuse of a pool of preallocated strings/buffers. virtual Future<Nothing> send(const std::string& data); @@ -110,18 +162,22 @@ public: virtual Socket::Kind kind() const = 0; - // Construct a new Socket from the given impl. This is a proxy - // function, as Impls derived from this won't have access to the - // Socket::Socket(...) constructors. - // - // TODO(jmlvanre): These should be protected; however, gcc - // complains when using them from within a lambda of a derived - // class. + /** + * Construct a new `Socket` from the given impl. + * + * This is a proxy function, as `Impl`s derived from this won't have + * access to the Socket::Socket(...) constructors. + */ + // TODO(jmlvanre): These should be protected; however, gcc complains + // when using them from within a lambda of a derived class. static Socket socket(std::shared_ptr<Impl>&& that) { return Socket(std::move(that)); } + /** + * @copydoc process::network::Socket::Impl::socket + */ static Socket socket(const std::shared_ptr<Impl>& that) { return Socket(that); @@ -130,10 +186,14 @@ public: protected: explicit Impl(int _s) : s(_s) { CHECK(s >= 0); } - // Construct a Socket wrapper from this implementation. + /** + * Construct a `Socket` wrapper from this implementation. + */ Socket socket() { return Socket(shared_from_this()); } - // Returns a std::shared_ptr<T> from this implementation. + /** + * Returns a `std::shared_ptr<T>` from this implementation. + */ template <typename T> static std::shared_ptr<T> shared(T* t) {
