Sync up the libc and linux_raw thread APIs. (#143)

* Sync up the libc and linux_raw thread APIs.

Reorganize and document things in the libc and linux_raw thread APIs so
that they're closer to each other.

* Sync up the signal APIs too.

* Minor cleanup: rename the naked macro to naked_fn.

Author: sunfishcode

src/arch/aarch64.rs

@@ -18,7 +18,7 @@ use {
 };
 
 #[cfg(feature = "origin-start")]
-naked!(
+naked_fn!(
     "
     The program entry point.
 
@@ -273,7 +273,7 @@ pub(super) unsafe fn munmap_and_exit_thread(map_addr: *mut c_void, map_len: usiz
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the `__NR_rt_sigreturn` system call to return control from a signal
     handler.

src/arch/arm.rs

@@ -18,7 +18,7 @@ use {
 };
 
 #[cfg(feature = "origin-start")]
-naked!(
+naked_fn!(
     "
     The program entry point.
 
@@ -287,7 +287,7 @@ pub(super) unsafe fn munmap_and_exit_thread(map_addr: *mut c_void, map_len: usiz
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the `__NR_rt_sigreturn` system call to return control from a signal
     handler.
@@ -312,7 +312,7 @@ fn test_rt_sigreturn() {
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the appropriate system call to return control from a signal
     handler that does not use `SA_SIGINFO`.

src/arch/riscv64.rs

@@ -16,7 +16,7 @@ use {
 };
 
 #[cfg(feature = "origin-start")]
-naked!(
+naked_fn!(
     "
     The program entry point.
 

src/arch/x86.rs

@@ -24,7 +24,7 @@ use {
 };
 
 #[cfg(feature = "origin-start")]
-naked!(
+naked_fn!(
     "
     The program entry point.
 
@@ -377,7 +377,7 @@ pub(super) unsafe fn munmap_and_exit_thread(map_addr: *mut c_void, map_len: usiz
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the `__NR_rt_sigreturn` system call to return control from a signal
     handler.
@@ -403,7 +403,7 @@ fn test_rt_sigreturn() {
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the appropriate system call to return control from a signal
     handler that does not use `SA_SIGINFO`.

src/arch/x86_64.rs

@@ -19,7 +19,7 @@ use {
 };
 
 #[cfg(feature = "origin-start")]
-naked!(
+naked_fn!(
     "
     The program entry point.
 
@@ -282,7 +282,7 @@ pub(super) unsafe fn munmap_and_exit_thread(map_addr: *mut c_void, map_len: usiz
 }
 
 #[cfg(feature = "signal")]
-naked!(
+naked_fn!(
     "
     Invoke the `__NR_rt_sigreturn` system call to return control from a signal
     handler.

src/naked.rs

@@ -3,7 +3,7 @@
 //! # Example
 //!
 //! ```no_compile
-//! naked!(
+//! naked_fn!(
 //!     "
 //!     A documentation comment.
 //!
@@ -35,7 +35,7 @@
 /// `global_asm` otherwise. This macro supports a limited subset of the
 /// features of `#[naked]`.
 #[cfg(feature = "nightly")]
-macro_rules! naked {
+macro_rules! naked_fn {
     (
         $doc:literal;
         $vis:vis fn $name:ident $args:tt -> $ret:ty;
@@ -60,7 +60,7 @@ macro_rules! naked {
 /// `global_asm` otherwise. This macro supports a limited subset of the
 /// features of `#[naked]`.
 #[cfg(not(feature = "nightly"))]
-macro_rules! naked {
+macro_rules! naked_fn {
     (
         $doc:literal;
         $vis:vis fn $name:ident $args:tt -> $ret:ty;

src/signal/libc.rs

@@ -24,7 +24,7 @@ pub use linux_raw_sys::ctypes::c_int as Sigflags;
 ///
 /// # Safety
 ///
-/// yolo
+/// yolo. At least this function handles `sa_restorer` automatically though.
 pub unsafe fn sigaction(sig: Signal, action: Option<Sigaction>) -> io::Result<Sigaction> {
     let action: *const Sigaction = match action {
         Some(action) => &action,

src/signal/linux_raw.rs

@@ -45,7 +45,7 @@ pub unsafe fn sigaction(sig: Signal, action: Option<Sigaction>) -> io::Result<Si
 
 /// Return a special “ignore” signal handler for ignoring signals.
 ///
-/// If you're looking for `sig_dlf`; use [`SigDfl`].
+/// If you're looking for `sig_dfl`; use [`SigDfl`].
 #[doc(alias = "SIG_IGN")]
 #[must_use]
 pub const fn sig_ign() -> Sighandler {

src/thread/libc.rs

@@ -1,4 +1,11 @@
 //! Thread startup and shutdown.
+//!
+//! Why does this api look like `thread::join(t)` instead of `t.join()`? Either
+//! way could work, but free functions help emphasize that this API's
+//! [`Thread`] differs from `std::thread::Thread`. It does not detach or free
+//! its resources on drop, and does not guarantee validity. That gives users
+//! more control when creating efficient higher-level abstractions like
+//! pthreads or `std::thread::Thread`.
 
 #[cfg(not(feature = "nightly"))]
 use crate::ptr::{with_exposed_provenance_mut, without_provenance_mut, Polyfill as _};
@@ -48,6 +55,16 @@ impl Thread {
         Self(raw.expose_provenance() as libc::pthread_t)
     }
 
+    /// Convert to `Self` from a raw non-null pointer.
+    ///
+    /// # Safety
+    ///
+    /// `raw` must be a valid non-null thread pointer.
+    #[inline]
+    pub unsafe fn from_raw_unchecked(raw: *mut c_void) -> Self {
+        Self::from_raw(raw)
+    }
+
     /// Convert to `Self` from a raw non-null pointer that was returned from
     /// `Thread::to_raw_non_null`.
     #[inline]
@@ -83,29 +100,33 @@ impl Thread {
 ///
 /// # Safety
 ///
-/// `fn_(arg)` on the new thread must have defined behavior, and the return
-/// value must be valid to use on the eventual joining thread.
+/// The values of `args` must be valid to send to the new thread, `fn_(args)`
+/// on the new thread must have defined behavior, and the return value must be
+/// valid to send to other threads.
 pub unsafe fn create(
-    fn_: unsafe fn(&mut [*mut c_void]) -> Option<NonNull<c_void>>,
+    fn_: unsafe fn(&mut [Option<NonNull<c_void>>]) -> Option<NonNull<c_void>>,
     args: &[Option<NonNull<c_void>>],
     stack_size: usize,
     guard_size: usize,
 ) -> io::Result<Thread> {
     extern "C" fn start(thread_arg_ptr: *mut c_void) -> *mut c_void {
         unsafe {
             // Unpack the thread arguments.
-            let num_args = thread_arg_ptr.cast::<*mut c_void>().read().addr();
-            let thread_args =
-                slice::from_raw_parts_mut(thread_arg_ptr.cast::<*mut c_void>(), num_args + 2);
-            let fn_: unsafe fn(&mut [*mut c_void]) -> Option<NonNull<c_void>> =
+            let thread_arg_ptr = thread_arg_ptr.cast::<Option<NonNull<c_void>>>();
+            let num_args = match thread_arg_ptr.read() {
+                Some(ptr) => ptr.as_ptr().addr(),
+                None => 0,
+            };
+            let thread_args = slice::from_raw_parts_mut(thread_arg_ptr, num_args + 2);
+            let fn_: unsafe fn(&mut [Option<NonNull<c_void>>]) -> Option<NonNull<c_void>> =
                 transmute(thread_args[1]);
             let args = &mut thread_args[2..];
 
             // Call the user's function.
             let return_value = fn_(args);
 
             // Free the thread argument memory.
-            libc::free(thread_arg_ptr);
+            libc::free(thread_arg_ptr.cast::<c_void>());
 
             // Return the return value.
             match return_value {
@@ -155,6 +176,40 @@ pub unsafe fn create(
     }
 }
 
+/// Marks a thread as “detached”.
+///
+/// Detached threads free their own resources automatically when they
+/// exit, rather than when they are joined.
+///
+/// # Safety
+///
+/// `thread` must point to a valid thread record that has not yet been detached
+/// and will not be joined.
+#[inline]
+pub unsafe fn detach(thread: Thread) {
+    let thread = thread.0;
+
+    assert_eq!(libc::pthread_detach(thread), 0);
+}
+
+/// Waits for a thread to finish.
+///
+/// The return value is the value returned from the call to the `fn_` passed to
+/// `create_thread`.
+///
+/// # Safety
+///
+/// `thread` must point to a valid thread record that has not already been
+/// detached or joined.
+pub unsafe fn join(thread: Thread) -> Option<NonNull<c_void>> {
+    let thread = thread.0;
+
+    let mut return_value: *mut c_void = null_mut();
+    assert_eq!(libc::pthread_join(thread, &mut return_value), 0);
+
+    NonNull::new(return_value)
+}
+
 /// Registers a function to call when the current thread exits.
 #[cfg(feature = "thread-at-exit")]
 pub fn at_exit(func: Box<dyn FnOnce()>) {
@@ -235,7 +290,8 @@ pub fn current_tls_addr(module: usize, offset: usize) -> *mut c_void {
 ///
 /// `thread` must point to a valid thread record.
 #[inline]
-pub unsafe fn thread_stack(thread: Thread) -> (*mut c_void, usize, usize) {
+#[must_use]
+pub unsafe fn stack(thread: Thread) -> (*mut c_void, usize, usize) {
     let thread = thread.0;
 
     let mut attr: libc::pthread_attr_t = zeroed();
@@ -254,40 +310,6 @@ pub unsafe fn thread_stack(thread: Thread) -> (*mut c_void, usize, usize) {
     (stack_addr, stack_size, guard_size)
 }
 
-/// Marks a thread as “detached”.
-///
-/// Detached threads free their own resources automatically when they
-/// exit, rather than when they are joined.
-///
-/// # Safety
-///
-/// `thread` must point to a valid thread record that has not yet been detached
-/// and will not be joined.
-#[inline]
-pub unsafe fn detach(thread: Thread) {
-    let thread = thread.0;
-
-    assert_eq!(libc::pthread_detach(thread), 0);
-}
-
-/// Waits for a thread to finish.
-///
-/// The return value is the value returned from the call to the `fn_` passed to
-/// `create_thread`.
-///
-/// # Safety
-///
-/// `thread` must point to a valid thread record that has not already been
-/// detached or joined.
-pub unsafe fn join(thread: Thread) -> Option<NonNull<c_void>> {
-    let thread = thread.0;
-
-    let mut return_value: *mut c_void = null_mut();
-    assert_eq!(libc::pthread_join(thread, &mut return_value), 0);
-
-    NonNull::new(return_value)
-}
-
 /// Return the default stack size for new threads.
 #[inline]
 #[must_use]

src/thread/linux_raw.rs

@@ -33,6 +33,8 @@ use rustix::runtime::{exe_phdrs, set_tid_address};
 use rustix::runtime::{sigprocmask, How, Sigset};
 use rustix::thread::gettid;
 
+pub use rustix::thread::Pid as ThreadId;
+
 /// An opaque pointer to a thread.
 ///
 /// This type does not detach or free resources on drop. It just leaks the
@@ -310,9 +312,6 @@ extern "C" {
 // Rust has `extern_weak` but it isn't stable, so use a `global_asm`.
 core::arch::global_asm!(".weak _DYNAMIC");
 
-/// A numerical thread identifier.
-pub use rustix::thread::Pid as ThreadId;
-
 /// Initialize the main thread.
 ///
 /// This function is similar to `create_thread` except that the OS thread is
@@ -807,8 +806,8 @@ pub(crate) fn call_dtors(current: Thread) {
 ///
 /// # Safety
 ///
-/// `thread` must point to a valid thread record that has not yet been
-/// detached and will not be joined.
+/// `thread` must point to a valid thread record that has not yet been detached
+/// and will not be joined.
 #[inline]
 pub unsafe fn detach(thread: Thread) {
     #[cfg(feature = "log")]
@@ -1053,13 +1052,11 @@ pub fn current_tls_addr(module: usize, offset: usize) -> *mut c_void {
 
 /// Return the id of a thread, or `None` if the thread has exited.
 ///
-/// This is the same as [`rustix::thread::gettid`], but loads the value from a
-/// field in the runtime rather than making a system call.
-///
 /// # Safety
 ///
 /// `thread` must point to a valid thread record.
 #[inline]
+#[cfg_attr(docsrs, doc(cfg(feature = "take-charge")))]
 pub unsafe fn id(thread: Thread) -> Option<ThreadId> {
     let raw = thread.0.as_ref().thread_id.load(SeqCst);
     ThreadId::from_raw(raw)