process::io Namespace Reference

Namespaces
	internal

Functions
Try< Nothing >	prepare_async (int_fd fd)
	Prepares a file descriptor to be ready for asynchronous IO. More...
Try< bool >	is_async (int_fd fd)
	Checks if io::prepare_async has been called on the file descriptor. More...
Future< short >	poll (int_fd fd, short events)
	Returns the events (a subset of the events specified) that can be performed on the specified file descriptor without blocking. More...
Future< size_t >	read (int_fd fd, void *data, size_t size)
	Performs a single non-blocking read by polling on the specified file descriptor until any data can be be read. More...
Future< std::string >	read (int_fd fd)
	Performs a series of asynchronous reads, until EOF is reached. More...
Future< size_t >	write (int_fd fd, const void *data, size_t size)
	Performs a single non-blocking write by polling on the specified file descriptor until data can be be written. More...
Future< Nothing >	write (int_fd fd, const std::string &data)
	Performs a series of asynchronous writes, until all of data has been written. More...
Future< Nothing >	redirect (int_fd from, Option< int_fd > to, size_t chunk=4096, const std::vector< lambda::function< void(const std::string &)>> &hooks={})
	Redirect output from the 'from' file descriptor to the 'to' file descriptor (or /dev/null if 'to' is None). More...

Variables
const short	READ = 0x01
	A possible event while polling. More...
const short	WRITE = 0x02
	A possible event while polling. More...
const size_t	BUFFERED_READ_SIZE = 16*4096
	Buffered read chunk size. More...

Function Documentation

Try<bool> process::io::is_async

(

int_fd

fd

)

Checks if io::prepare_async has been called on the file descriptor.

Returns

Returns if the file descriptor is asynchronous. An asynchronous file descriptor is defined to be non-blocking on POSIX systems and overlapped and associated with an IO completion port on Windows. An error will be returned if the file descriptor is invalid.

Future<short> process::io::poll	(	int_fd	fd,
		short	events
	)

Returns the events (a subset of the events specified) that can be performed on the specified file descriptor without blocking.

Note that on windows, only io::READ is available (under the covers this is achieved via a zero byte read).

See also

process::io::READ

process::io::WRITE

Try<Nothing> process::io::prepare_async

(

int_fd

fd

)

Prepares a file descriptor to be ready for asynchronous IO.

On POSIX systems, this sets the file descriptor to non-blocking. On Windows, this will assign the file descriptor to an IO completion port.

NOTE: Because the IO completion port is only known at the libprocess level, we need this function instead of simply using stout's os::nonblock and os::isNonblock functions like we could do for POSIX systems.

Returns

On success, returns Nothing. On error, returns an Error.

Future<size_t> process::io::read	(	int_fd	fd,
		void *	data,
		size_t	size
	)

Performs a single non-blocking read by polling on the specified file descriptor until any data can be be read.

io::prepare_async needs to be called beforehand.

The future will become ready when some data is read (may be less than the specified size).

To provide a consistent interface, a zero byte will immediately return a ready future with 0 bytes. For users looking to use the zero byte read trick on windows to achieve read readiness polling, just use io::poll with io::READ.

Returns

The number of bytes read or zero on EOF (or if zero bytes were requested). A failure will be returned if an error is detected.

Future<std::string> process::io::read

(

int_fd

fd

)

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.

Returns

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<Nothing> process::io::redirect	(	int_fd	from,
		Option< int_fd >	to,
		size_t	chunk = 4096,
		const std::vector< lambda::function< void(const std::string &)>> &	hooks = {}
	)

Redirect output from the 'from' file descriptor to the 'to' file descriptor (or /dev/null if 'to' is None).

Optionally call a vector of callback hooks, passing them the data before it is written to 'to'.

The 'to' and 'from' file descriptors will be duplicated so that the file descriptors' lifetimes can be controlled within this function.

Returns

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<size_t> process::io::write	(	int_fd	fd,
		const void *	data,
		size_t	size
	)

Performs a single non-blocking write by polling on the specified file descriptor until data can be be written.

io::prepare_async needs to be called beforehand.

The future will become ready when some data is written (may be less than the specified size of the data).

Returns

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<Nothing> process::io::write ( int_fd  fd, const std::string &  data  )

inline

Performs a series of asynchronous writes, until all of data has been written.

Returns

Nothing or a failure if an error 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.

Variable Documentation

const size_t process::io::BUFFERED_READ_SIZE = 16*4096

Buffered read chunk size.

Roughly 16 pages.

const short process::io::READ = 0x01

A possible event while polling.

See also

process::io::poll

const short process::io::WRITE = 0x02

A possible event while polling.

See also

process::io::poll