//! 特定于 Linux 的 [`std::process`] 模块中的原语扩展。
//!
//! [`std::process`]: crate::process

#![unstable(feature = "linux_pidfd", issue = "82971")]

use crate::io::Result;
use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
use crate::process;
use crate::sealed::Sealed;
#[cfg(not(doc))]
use crate::sys::fd::FileDesc;
use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner};

#[cfg(doc)]
struct FileDesc;

/// 此类型表示引用进程的文件描述符。
///
/// `PidFd` 可以通过设置 [`Command`] 和 [`create_pidfd`] 上的相应选项来获得。随后，可以通过调用 [`pidfd`] 或 [`take_pidfd`] 从 [`Child`] 中检索创建的 pidfd。
///
/// Example:
///
/// ```no_run
/// #![feature(linux_pidfd)]
/// use std::os::linux::process::{CommandExt, ChildExt};
/// use std::process::Command;
///
/// let mut child = Command::new("echo")
///     .create_pidfd(true)
///     .spawn()
///     .expect("Failed to spawn child");
///
/// let pidfd = child
///     .take_pidfd()
///     .expect("Failed to retrieve pidfd");
///
/// // 当 `pidfd` 关闭时，文件描述符将被关闭。
/// ```
///
/// 有关详细信息，请参见 [`pidfd_open(2)`] 的手册页。
///
/// [`Command`]: process::Command
/// [`create_pidfd`]: CommandExt::create_pidfd
/// [`Child`]: process::Child
/// [`pidfd`]: fn@ChildExt::pidfd
/// [`take_pidfd`]: ChildExt::take_pidfd
/// [`pidfd_open(2)`]: https://man7.org/linux/man-pages/man2/pidfd_open.2.html
#[derive(Debug)]
pub struct PidFd {
    inner: FileDesc,
}

impl AsInner<FileDesc> for PidFd {
    #[inline]
    fn as_inner(&self) -> &FileDesc {
        &self.inner
    }
}

impl FromInner<FileDesc> for PidFd {
    fn from_inner(inner: FileDesc) -> PidFd {
        PidFd { inner }
    }
}

impl IntoInner<FileDesc> for PidFd {
    fn into_inner(self) -> FileDesc {
        self.inner
    }
}

impl AsRawFd for PidFd {
    #[inline]
    fn as_raw_fd(&self) -> RawFd {
        self.as_inner().as_raw_fd()
    }
}

impl FromRawFd for PidFd {
    unsafe fn from_raw_fd(fd: RawFd) -> Self {
        Self::from_inner(FileDesc::from_raw_fd(fd))
    }
}

impl IntoRawFd for PidFd {
    fn into_raw_fd(self) -> RawFd {
        self.into_inner().into_raw_fd()
    }
}

impl AsFd for PidFd {
    fn as_fd(&self) -> BorrowedFd<'_> {
        self.as_inner().as_fd()
    }
}

impl From<OwnedFd> for PidFd {
    fn from(fd: OwnedFd) -> Self {
        Self::from_inner(FileDesc::from_inner(fd))
    }
}

impl From<PidFd> for OwnedFd {
    fn from(pid_fd: PidFd) -> Self {
        pid_fd.into_inner().into_inner()
    }
}

/// 特定于操作系统的 [`Child`] 的扩展
///
/// [`Child`]: process::Child
pub trait ChildExt: Sealed {
    /// 获取对为此 [`Child`] 创建的 [`PidFd`] 的引用 (如果可用)。
    ///
    /// 只有在创建相应的 [`Command`] 时使用 [`create_pidfd`] 请求创建 pidfd 时，pidfd 才可用。
    ///
    ///
    /// 即使请求，pidfd 也可能不可用，因为正在使用旧版本的 Linux，或者如果发生了一些其他错误。
    ///
    /// [`Command`]: process::Command
    /// [`create_pidfd`]: CommandExt::create_pidfd
    /// [`Child`]: process::Child
    ///
    fn pidfd(&self) -> Result<&PidFd>;

    /// 拥有为此 [`Child`] 创建的 [`PidFd`] (如果可用) 的所有权。
    ///
    /// 只有在创建相应的 [`Command`] 时使用 [`create_pidfd`] 请求创建 pidfd 时，pidfd 才可用。
    ///
    ///
    /// 即使请求，pidfd 也可能不可用，因为正在使用旧版本的 Linux，或者如果发生了一些其他错误。
    ///
    /// [`Command`]: process::Command
    /// [`create_pidfd`]: CommandExt::create_pidfd
    /// [`Child`]: process::Child
    ///
    fn take_pidfd(&mut self) -> Result<PidFd>;
}

/// 特定于操作系统的 [`Command`] 的扩展
///
/// [`Command`]: process::Command
pub trait CommandExt: Sealed {
    /// 设置是否应为此 [`Command`] 生成的 [`Child`] 创建 [`PidFd`](struct@PidFd)。
    ///
    /// 默认情况下，不会创建 pidfd。
    ///
    /// 可以使用 [`pidfd`] 或 [`take_pidfd`] 从子节点那里检索 pidfd。
    ///
    /// pidfd 只会在有可能以保证无竞争的方式 (例如
    /// 如果支持 `clone3` 系统调用)。
    /// 否则，[`pidfd`] 将返回错误。
    ///
    /// [`Command`]: process::Command
    /// [`Child`]: process::Child
    /// [`pidfd`]: fn@ChildExt::pidfd
    /// [`take_pidfd`]: ChildExt::take_pidfd
    fn create_pidfd(&mut self, val: bool) -> &mut process::Command;
}

impl CommandExt for process::Command {
    fn create_pidfd(&mut self, val: bool) -> &mut process::Command {
        self.as_inner_mut().create_pidfd(val);
        self
    }
}