Crate filedescriptor

The purpose of this crate is to make it a bit more ergonomic for portable applications that need to work with the platform level RawFd and RawHandle types.

Rather than conditionally using RawFd and RawHandle, the FileDescriptor type can be used to manage ownership, duplicate, read and write.

FileDescriptor

This is a bit of a contrived example, but demonstrates how to avoid the conditional code that would otherwise be required to deal with calling as_raw_fd and as_raw_handle:

use filedescriptor::{FileDescriptor, FromRawFileDescriptor, Result};
use std::io::Write;

fn get_stdout() -> Result<FileDescriptor> {
  let stdout = std::io::stdout();
  let handle = stdout.lock();
  FileDescriptor::dup(&handle)
}

fn print_something() -> Result<()> {
   get_stdout()?.write(b"hello")?;
   Ok(())
}

Pipe

The Pipe type makes it more convenient to create a pipe and manage the lifetime of both the read and write ends of that pipe.

use filedescriptor::{Pipe, Error};
use std::io::{Read, Write};

let mut pipe = Pipe::new()?;
pipe.write.write(b"hello")?;
drop(pipe.write);

let mut s = String::new();
pipe.read.read_to_string(&mut s)?;
assert_eq!(s, "hello");

Socketpair

The socketpair function returns a pair of connected SOCK_STREAM sockets and functions both on posix and windows systems.

use std::io::{Read, Write};
use filedescriptor::Error;

let (mut a, mut b) = filedescriptor::socketpair()?;
a.write(b"hello")?;
drop(a);

let mut s = String::new();
b.read_to_string(&mut s)?;
assert_eq!(s, "hello");

Polling

The mio crate offers powerful and scalable IO multiplexing, but there are some situations where mio doesn’t fit. The filedescriptor crate offers a poll(2) compatible interface suitable for testing the readiness of a set of file descriptors. On unix systems this is a very thin wrapper around poll(2), except on macOS where it is actually a wrapper around the select(2) interface. On Windows systems the winsock WSAPoll function is used instead.

use filedescriptor::*;
use std::time::Duration;
use std::io::{Read, Write};

let (mut a, mut b) = filedescriptor::socketpair()?;
let mut poll_array = [pollfd {
   fd: a.as_socket_descriptor(),
   events: POLLIN,
   revents: 0
}];
// sleeps for 20 milliseconds because `a` is not yet ready
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 0);

b.write(b"hello")?;

// Now a is ready for read
assert_eq!(poll(&mut poll_array, Some(Duration::from_millis(20)))?, 1);

Structs

FileDescriptor

FileDescriptor is a thin wrapper on top of the OwnedHandle type that exposes the ability to Read and Write to the platform RawFileDescriptor.

OwnedHandle

OwnedHandle allows managing the lifetime of the platform RawFileDescriptor type. It is exposed in the interface of this crate primarily for convenience on Windows where the system handle type is used for a variety of objects that don’t support reading and writing.

Pipe

Represents the readable and writable ends of a pair of descriptors connected via a kernel pipe.

pollfd

Enums

Error

StdioDescriptor

Constants

POLLERR

POLLHUP

POLLIN

POLLOUT

Traits

AsRawFileDescriptor

AsRawFileDescriptor is a platform independent trait for returning a non-owning reference to the underlying platform file descriptor type.

AsRawSocketDescriptor

FromRawFileDescriptor

FromRawFileDescriptor is a platform independent trait for creating an instance from the underlying platform file descriptor type. Because the platform file descriptor type has no inherent ownership management, the from_raw_file_descriptor function is marked as unsafe to indicate that care must be taken by the caller to ensure that it is used appropriately.

FromRawSocketDescriptor

IntoRawFileDescriptor

IntoRawFileDescriptor is a platform independent trait for converting an instance into the underlying platform file descriptor type.

IntoRawSocketDescriptor

Functions

poll

Examines a set of FileDescriptors to see if some of them are ready for I/O, or if certain events have occurred on them.

socketpair

Create a pair of connected sockets

Type Aliases

RawFileDescriptor

RawFileDescriptor is a platform independent type alias for the underlying platform file descriptor type. It is primarily useful for avoiding using cfg blocks in platform independent code.

Result

SocketDescriptor

SocketDescriptor is a platform independent type alias for the underlying platform socket descriptor type. It is primarily useful for avoiding using cfg blocks in platform independent code.