From cee1695e0839d0672113e7445cec0722559585ee Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 31 Jan 2016 11:50:22 -0800 Subject: Safety docs about `std::process::Child` going out of scope There is no `Drop` implemented for `Child`, so if it goes out of scope in Rust-land and gets deallocated, the child process will continue to exist and execute. If users want a guarantee that the process has finished running and exited they must manually use `kill`, `wait`, or `wait_with_output`. Fixes #31289. --- src/libstd/process.rs | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7197dfa8b2d..2cfbef1e1b7 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -47,6 +47,14 @@ use thread::{self, JoinHandle}; /// /// assert!(ecode.success()); /// ``` +/// +/// # Safety +/// +/// Take note that there is no implementation of +/// [`Drop`](../../core/ops/trait.Drop.html) for child processes, so if you +/// not ensure the `Child` has exited (through `kill`, `wait`, or +/// `wait_with_output`) then it will continue to run even after the `Child` +/// handle to it has gone out of scope. #[stable(feature = "process", since = "1.0.0")] pub struct Child { handle: imp::Process, -- cgit 1.4.1-3-g733a5 From 76839221ff9bc4fd65ab9e7c0f1cd8e7514446f0 Mon Sep 17 00:00:00 2001 From: Dirk Gadsden Date: Sun, 31 Jan 2016 12:33:37 -0800 Subject: Minor corrections in docs for `std::process::Child` --- src/libstd/process.rs | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'src/libstd') diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 2cfbef1e1b7..5e0a54392d2 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -48,13 +48,15 @@ use thread::{self, JoinHandle}; /// assert!(ecode.success()); /// ``` /// -/// # Safety +/// # Note /// /// Take note that there is no implementation of /// [`Drop`](../../core/ops/trait.Drop.html) for child processes, so if you -/// not ensure the `Child` has exited (through `kill`, `wait`, or -/// `wait_with_output`) then it will continue to run even after the `Child` -/// handle to it has gone out of scope. +/// do not ensure the `Child` has exited then it will continue to run, even +/// after the `Child` handle to the child process has gone out of scope. +/// +/// Calling `wait` (or other functions that wrap around it) will make the +/// parent process wait until the child has actually exited before continuing. #[stable(feature = "process", since = "1.0.0")] pub struct Child { handle: imp::Process, -- cgit 1.4.1-3-g733a5 From 129a6239d28aeaea87a9d27191e50b55e6b8923a Mon Sep 17 00:00:00 2001 From: Kamal Marhubi Date: Mon, 1 Feb 2016 21:41:29 -0500 Subject: docs: Standardize on 'Errors' header in std docs --- src/libcollections/str.rs | 2 +- src/libcollections/string.rs | 2 +- src/libcore/str/mod.rs | 2 +- src/librustc_unicode/char.rs | 2 +- src/libstd/fs.rs | 2 +- src/libstd/sync/condvar.rs | 2 +- src/libstd/sync/mutex.rs | 8 ++++---- src/libstd/sync/rwlock.rs | 12 ++++++------ src/libstd/sys/common/remutex.rs | 4 ++-- 9 files changed, 18 insertions(+), 18 deletions(-) (limited to 'src/libstd') diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index 094b7f1d034..118675ab2c5 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -1644,7 +1644,7 @@ impl str { /// /// [`FromStr`]: str/trait.FromStr.html /// - /// # Failure + /// # Errors /// /// Will return `Err` if it's not possible to parse this string slice into /// the desired type. diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 97c12043e76..b1242ba6d4d 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -433,7 +433,7 @@ impl String { /// /// [`str::from_utf8()`]: ../str/fn.from_utf8.html /// - /// # Failure + /// # Errors /// /// Returns `Err` if the slice is not UTF-8 with a description as to why the /// provided bytes are not UTF-8. The vector you moved in is also included. diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 3892455395f..f19970546d7 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -188,7 +188,7 @@ impl Utf8Error { /// it, this function is one way to have a stack-allocated string. There is /// an example of this in the examples section below. /// -/// # Failure +/// # Errors /// /// Returns `Err` if the slice is not UTF-8 with a description as to why the /// provided slice is not UTF-8. diff --git a/src/librustc_unicode/char.rs b/src/librustc_unicode/char.rs index 46ecd3a80b5..9386453d660 100644 --- a/src/librustc_unicode/char.rs +++ b/src/librustc_unicode/char.rs @@ -194,7 +194,7 @@ impl char { /// * `a-z` /// * `A-Z` /// - /// # Failure + /// # Errors /// /// Returns `None` if the `char` does not refer to a digit in the given radix. /// diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index e40a3d06f77..d12cfa6183a 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -70,7 +70,7 @@ pub struct Metadata(fs_imp::FileAttr); /// information like the entry's path and possibly other metadata can be /// learned. /// -/// # Failure +/// # Errors /// /// This `io::Result` will be an `Err` if there's some sort of intermittent /// IO error during iteration. diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs index 1f7fe820bf8..9a786752365 100644 --- a/src/libstd/sync/condvar.rs +++ b/src/libstd/sync/condvar.rs @@ -129,7 +129,7 @@ impl Condvar { /// the predicate must always be checked each time this function returns to /// protect against spurious wakeups. /// - /// # Failure + /// # Errors /// /// This function will return an error if the mutex being waited on is /// poisoned when this thread re-acquires the lock. For more information, diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 6b20e51967d..fe9f0371abd 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -205,7 +205,7 @@ impl Mutex { /// held. An RAII guard is returned to allow scoped unlock of the lock. When /// the guard goes out of scope, the mutex will be unlocked. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error once the mutex is acquired. @@ -223,7 +223,7 @@ impl Mutex { /// /// This function does not block. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be @@ -250,7 +250,7 @@ impl Mutex { /// Consumes this mutex, returning the underlying data. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error instead. @@ -280,7 +280,7 @@ impl Mutex { /// Since this call borrows the `Mutex` mutably, no actual locking needs to /// take place---the mutable borrow statically guarantees no locks exist. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error instead. diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index 3dbef435481..63ef7732ad6 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -169,7 +169,7 @@ impl RwLock { /// Returns an RAII guard which will release this thread's shared access /// once it is dropped. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. @@ -192,7 +192,7 @@ impl RwLock { /// This function does not provide any guarantees with respect to the ordering /// of whether contentious readers or writers will acquire the lock first. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -217,7 +217,7 @@ impl RwLock { /// Returns an RAII guard which will drop the write access of this rwlock /// when dropped. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. @@ -240,7 +240,7 @@ impl RwLock { /// This function does not provide any guarantees with respect to the ordering /// of whether contentious readers or writers will acquire the lock first. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -269,7 +269,7 @@ impl RwLock { /// Consumes this `RwLock`, returning the underlying data. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -301,7 +301,7 @@ impl RwLock { /// Since this call borrows the `RwLock` mutably, no actual locking needs to /// take place---the mutable borrow statically guarantees no locks exist. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An diff --git a/src/libstd/sys/common/remutex.rs b/src/libstd/sys/common/remutex.rs index 31caa68c4b7..2e2be63c3cb 100644 --- a/src/libstd/sys/common/remutex.rs +++ b/src/libstd/sys/common/remutex.rs @@ -78,7 +78,7 @@ impl ReentrantMutex { /// calling this method already holds the lock, the call shall succeed without /// blocking. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be @@ -95,7 +95,7 @@ impl ReentrantMutex { /// /// This function does not block. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be -- cgit 1.4.1-3-g733a5