Skip to content

Commit

Permalink
Expand documentation of process::exit and exec
Browse files Browse the repository at this point in the history
Show a conventional way to use process::exit when destructors are considered important and also
mention that the same caveats wrt destructors apply to exec as well.
  • Loading branch information
nagisa committed Jan 19, 2017
1 parent 3dcb288 commit c2eab73
Show file tree
Hide file tree
Showing 2 changed files with 29 additions and 2 deletions.
21 changes: 19 additions & 2 deletions src/libstd/process.rs
Original file line number Diff line number Diff line change
Expand Up @@ -924,10 +924,27 @@ impl Child {
///
/// # Examples
///
/// Due to this function’s behavior regarding destructors, a conventional way
/// to use the function is to extract the actual computation to another
/// function and compute the exit code from its return value:
///
/// ```
/// use std::process;
/// use std::io::{self, Write};
///
/// fn run_app() -> Result<(), ()> {
/// // Application logic here
/// Ok(())
/// }
///
/// process::exit(0);
/// fn main() {
/// ::std::process::exit(match run_app() {
/// Ok(_) => 0,
/// Err(err) => {
/// writeln!(io::stderr(), "error: {:?}", err).unwrap();
/// 1
/// }
/// });
/// }
/// ```
///
/// Due to [platform-specific behavior], the exit code for this example will be
Expand Down
10 changes: 10 additions & 0 deletions src/libstd/sys/unix/ext/process.rs
Original file line number Diff line number Diff line change
Expand Up @@ -67,10 +67,20 @@ pub trait CommandExt {
/// an error indicating why the exec (or another part of the setup of the
/// `Command`) failed.
///
/// `exec` not returning has the same implications as calling
/// [`process::exit`] – no destructors on the current stack or any other
/// thread’s stack will be run. Therefore, it is recommended to only call
/// `exec` at a point where it is fine to not run any destructors. Note,
/// that the `execvp` syscall independently guarantees that all memory is
/// freed and all file descriptors with the `CLOEXEC` option (set by default
/// on all file descriptors opened by the standard library) are closed.
///
/// This function, unlike `spawn`, will **not** `fork` the process to create
/// a new child. Like spawn, however, the default behavior for the stdio
/// descriptors will be to inherited from the current process.
///
/// [`process::exit`]: ../../../process/fn.exit.html
///
/// # Notes
///
/// The process may be in a "broken state" if this function returns in
Expand Down

0 comments on commit c2eab73

Please sign in to comment.