Repository: mesos Updated Branches: refs/heads/master 940f52548 -> 69b8ae501
Doxygen-ification of comments in libprocess io.hpp. Review: https://reviews.apache.org/r/36279 Project: http://git-wip-us.apache.org/repos/asf/mesos/repo Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/69b8ae50 Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/69b8ae50 Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/69b8ae50 Branch: refs/heads/master Commit: 69b8ae5012294c0339cb0fe19d2902b3d370cfa9 Parents: 940f525 Author: Joseph Wu <[email protected]> Authored: Tue Jul 21 21:56:13 2015 -0700 Committer: Benjamin Hindman <[email protected]> Committed: Tue Jul 21 21:56:14 2015 -0700 ---------------------------------------------------------------------- 3rdparty/libprocess/include/process/io.hpp | 115 +++++++++++++++--------- 1 file changed, 75 insertions(+), 40 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/mesos/blob/69b8ae50/3rdparty/libprocess/include/process/io.hpp ---------------------------------------------------------------------- diff --git a/3rdparty/libprocess/include/process/io.hpp b/3rdparty/libprocess/include/process/io.hpp index 2457163..975923f 100644 --- a/3rdparty/libprocess/include/process/io.hpp +++ b/3rdparty/libprocess/include/process/io.hpp @@ -25,66 +25,101 @@ namespace process { namespace io { -// Possible events for polling. +/** + * A possible event while polling. + * + * @see process::io::poll + */ const short READ = 0x01; + +/** + * @copydoc process::io::READ + */ const short WRITE = 0x02; -// Buffered read chunk size. Roughly 16 pages. +/** + * Buffered read chunk size. + * + * Roughly 16 pages. + */ const size_t BUFFERED_READ_SIZE = 16*4096; +/** + * Returns the events (a subset of the events specified) that can be + * performed on the specified file descriptor without blocking. + * + * @see process::io::READ + * @see process::io::WRITE + */ // TODO(benh): Add a version which takes multiple file descriptors. -// Returns the events (a subset of the events specified) that can be -// performed on the specified file descriptor without blocking. Future<short> poll(int fd, short events); -// Performs a single non-blocking read by polling on the specified -// file descriptor until any data can be be read. The future will -// become ready when some data is read (may be less than that -// specified by size). A failure will be returned if an error is -// detected. If end-of-file is reached, value zero will be -// returned. Note that the return type of this function differs from -// the standard 'read'. In particular, this function returns the -// number of bytes read or zero on end-of-file (an error is indicated -// by failing the future, thus only a 'size_t' is necessary rather -// than a 'ssize_t'). +/** + * Performs a single non-blocking read by polling on the specified + * file descriptor until any data can be be read. + * + * The future will become ready when some data is read (may be less than + * the specified size). + * + * @return The number of bytes read or zero on EOF. + * A failure will be returned if an error is detected. + */ Future<size_t> read(int fd, void* data, size_t size); -// Performs a series of asynchronous reads, until EOF is reached. -// NOTE: When using this, ensure the sender will close the connection -// so that EOF can be reached. -// -// NOTE: the specified file descriptor is duplicated and set to -// close-on-exec and made non-blocking (which will return a failure if -// these operations can not be performed). +/** + * Performs a series of asynchronous reads, until EOF is reached. + * + * **NOTE**: when using this, ensure the sender will close the connection + * so that EOF can be reached. + * + * @return The concatentated result of the reads. + * A failure will be returned if the file descriptor is bad, or if the + * file descriptor cannot be duplicated, set to close-on-exec, + * or made non-blocking. + */ Future<std::string> read(int fd); -// Performs a non-blocking write by polling on the specified file -// descriptor until data can be be written. The future will become -// ready when some data is written with the number of bytes that were -// written. This may be less than the specified size of the data. A -// failure will be returned if an error is detected. In the special -// case of writing to a socket or pipe, an error will be returned if -// the read end of the socket or pipe has been closed. +/** + * Performs a single non-blocking write by polling on the specified + * file descriptor until data can be be written. + * + * The future will become ready when some data is written (may be less than + * the specified size of the data). + * + * @return The number of bytes written. + * A failure will be returned if an error is detected. + * If writing to a socket or pipe, an error will be returned if the + * the read end of the socket or pipe has been closed. + */ Future<size_t> write(int fd, void* data, size_t size); -// Performs a series of asynchronous writes until all of data has been -// written or an error occured in which case a failure is returned. -// -// NOTE: the specified file descriptor is duplicated and set to -// close-on-exec and made non-blocking (which will return a failure if -// these operations can not be performed). +/** + * Performs a series of asynchronous writes, until all of data has been + * written. + * + * @return Nothing or a failure if an error occured. + * A failure will be returned if the file descriptor is bad, or if the + * file descriptor cannot be duplicated, set to close-on-exec, + * or made non-blocking. + */ Future<Nothing> write(int fd, const std::string& data); - -// Redirect output from 'from' file descriptor to 'to' file descriptor -// or /dev/null if 'to' is None. Note that depending on how we -// redirect output we duplicate the 'from' and 'to' file descriptors -// so we can control their lifetimes. Returns after EOF has been hit -// on 'from' or some form of failure has occured. +/** + * Redirect output from the 'from' file descriptor to the 'to' file + * descriptor (or /dev/null if 'to' is None). + * + * The 'to' and 'from' file descriptors will be duplicated so that the + * file descriptors' lifetimes can be controlled within this function. + * + * @return Nothing after EOF has been encountered on 'from' or if a + * failure has occurred. A failure will be returned if the file + * descriptor is bad, or if the file descriptor cannot be duplicated, + * set to close-on-exec, or made non-blocking. + */ Future<Nothing> redirect(int from, Option<int> to, size_t chunk = 4096); } // namespace io {
