mirror of
https://github.com/wez/wezterm.git
synced 2024-08-17 02:00:25 +03:00
filedescriptor: add some doc comments
This commit is contained in:
parent
0f83309b58
commit
143617155e
@ -9,56 +9,109 @@ mod windows;
|
||||
#[cfg(windows)]
|
||||
pub use crate::windows::*;
|
||||
|
||||
/// `AsRawFileDescriptor` is a platform independent trait for returning
|
||||
/// a non-owning reference to the underlying platform file descriptor
|
||||
/// type.
|
||||
pub trait AsRawFileDescriptor {
|
||||
fn as_raw_file_descriptor(&self) -> RawFileDescriptor;
|
||||
}
|
||||
|
||||
/// `IntoRawFileDescriptor` is a platform independent trait for converting
|
||||
/// an instance into the underlying platform file descriptor type.
|
||||
pub trait IntoRawFileDescriptor {
|
||||
fn into_raw_file_descriptor(self) -> RawFileDescriptor;
|
||||
}
|
||||
|
||||
/// `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_descrptor` function is marked as unsafe
|
||||
/// to indicate that care must be taken by the caller to ensure that it
|
||||
/// is used appropriately.
|
||||
pub trait FromRawFileDescriptor {
|
||||
unsafe fn from_raw_file_descrptor(fd: RawFileDescriptor) -> Self;
|
||||
}
|
||||
|
||||
/// `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.
|
||||
#[derive(Debug)]
|
||||
pub struct OwnedHandle {
|
||||
handle: RawFileDescriptor,
|
||||
}
|
||||
|
||||
impl OwnedHandle {
|
||||
/// Create a new handle from some object that is convertible into
|
||||
/// the system `RawFileDescriptor` type. This consumes the parameter
|
||||
/// and replaces it with an `OwnedHandle` instance.
|
||||
pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
|
||||
Self {
|
||||
handle: f.into_raw_file_descriptor(),
|
||||
}
|
||||
}
|
||||
|
||||
/// Attempt to duplicate the underlying handle and return an
|
||||
/// `OwnedHandle` wrapped around the duplicate. Since the duplication
|
||||
/// requires kernel resources that may not be available, this is a
|
||||
/// potentially fallible operation.
|
||||
/// The returned handle has a separate lifetime from the source, but
|
||||
/// references the same object at the kernel level.
|
||||
pub fn try_clone(&self) -> Fallible<Self> {
|
||||
Self::dup(self)
|
||||
}
|
||||
|
||||
/// Attempt to duplicate the underlying handle from an object that is
|
||||
/// representable as the systemm `RawFileDescriptor` type and return an
|
||||
/// `OwnedHandle` wrapped around the duplicate. Since the duplication
|
||||
/// requires kernel resources that may not be available, this is a
|
||||
/// potentially fallible operation.
|
||||
/// The returned handle has a separate lifetime from the source, but
|
||||
/// references the same object at the kernel level.
|
||||
pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
|
||||
Self::dup_impl(f)
|
||||
}
|
||||
}
|
||||
|
||||
/// `FileDescriptor` is a thin wrapper on top of the `OwnedHandle` type that
|
||||
/// exposes the ability to Read and Write to the platform `RawFileDescriptor`.
|
||||
#[derive(Debug)]
|
||||
pub struct FileDescriptor {
|
||||
handle: OwnedHandle,
|
||||
}
|
||||
|
||||
impl FileDescriptor {
|
||||
/// Create a new descriptor from some object that is convertible into
|
||||
/// the system `RawFileDescriptor` type. This consumes the parameter
|
||||
/// and replaces it with a `FileDescriptor` instance.
|
||||
pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
|
||||
let handle = OwnedHandle::new(f);
|
||||
Self { handle }
|
||||
}
|
||||
|
||||
/// Attempt to duplicate the underlying handle from an object that is
|
||||
/// representable as the systemm `RawFileDescriptor` type and return a
|
||||
/// `FileDescriptor` wrapped around the duplicate. Since the duplication
|
||||
/// requires kernel resources that may not be available, this is a
|
||||
/// potentially fallible operation.
|
||||
/// The returned handle has a separate lifetime from the source, but
|
||||
/// references the same object at the kernel level.
|
||||
pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
|
||||
OwnedHandle::dup(f).map(|handle| Self { handle })
|
||||
}
|
||||
|
||||
/// Attempt to duplicate the underlying handle and return a
|
||||
/// `FileDescriptor` wrapped around the duplicate. Since the duplication
|
||||
/// requires kernel resources that may not be available, this is a
|
||||
/// potentially fallible operation.
|
||||
/// The returned handle has a separate lifetime from the source, but
|
||||
/// references the same object at the kernel level.
|
||||
pub fn try_clone(&self) -> Fallible<Self> {
|
||||
self.handle.try_clone().map(|handle| Self { handle })
|
||||
}
|
||||
}
|
||||
|
||||
pub struct Pipes {
|
||||
pub read: FileDescriptor,
|
||||
pub write: FileDescriptor,
|
||||
}
|
||||
|
||||
impl FileDescriptor {
|
||||
pub fn new<F: IntoRawFileDescriptor>(f: F) -> Self {
|
||||
let handle = OwnedHandle::new(f);
|
||||
Self { handle }
|
||||
}
|
||||
|
||||
pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
|
||||
OwnedHandle::dup(f).map(|handle| Self { handle })
|
||||
}
|
||||
|
||||
pub fn try_clone(&self) -> Fallible<Self> {
|
||||
self.handle.try_clone().map(|handle| Self { handle })
|
||||
}
|
||||
}
|
||||
|
@ -5,6 +5,9 @@ use crate::{
|
||||
use failure::{bail, Fallible};
|
||||
use std::os::unix::prelude::*;
|
||||
|
||||
/// `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.
|
||||
pub type RawFileDescriptor = RawFd;
|
||||
|
||||
impl<T: AsRawFd> AsRawFileDescriptor for T {
|
||||
@ -73,7 +76,8 @@ impl OwnedHandle {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn dup<F: AsRawFileDescriptor>(fd: &F) -> Fallible<Self> {
|
||||
#[inline]
|
||||
pub(crate) fn dup_impl<F: AsRawFileDescriptor>(fd: &F) -> Fallible<Self> {
|
||||
let fd = fd.as_raw_file_descriptor();
|
||||
let duped = unsafe { libc::dup(fd) };
|
||||
if duped == -1 {
|
||||
|
@ -12,6 +12,9 @@ use winapi::um::handleapi::*;
|
||||
use winapi::um::namedpipeapi::CreatePipe;
|
||||
use winapi::um::processthreadsapi::*;
|
||||
|
||||
/// `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.
|
||||
pub type RawFileDescriptor = RawHandle;
|
||||
|
||||
impl<T: AsRawHandle> AsRawFileDescriptor for T {
|
||||
@ -49,7 +52,8 @@ impl FromRawHandle for OwnedHandle {
|
||||
}
|
||||
|
||||
impl OwnedHandle {
|
||||
pub fn dup<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
|
||||
#[inline]
|
||||
pub(crate) fn dup_impl<F: AsRawFileDescriptor>(f: &F) -> Fallible<Self> {
|
||||
let handle = f.as_raw_file_descriptor();
|
||||
if handle == INVALID_HANDLE_VALUE || handle.is_null() {
|
||||
return Ok(OwnedHandle { handle });
|
||||
|
Loading…
Reference in New Issue
Block a user