RFC: Add std::process::exit

text/0000-process-exit.md

@@ -0,0 +1,88 @@
+- Feature Name: exit
+- Start Date: 2015-03-24
+- RFC PR: (leave this empty)
+- Rust Issue: (leave this empty)
+
+# Summary
+
+Add a function to the `std::process` module to exit the process immediately with
+a specified exit code.
+
+# Motivation
+
+Currently there is no stable method to exit a program in Rust with a nonzero
+exit code without panicking. The current unstable method for doing so is by
+using the `exit_status` feature with the `std::env::set_exit_status` function.
+
+This function has not been stabilized as it diverges from the system APIs (there
+is no equivalent) and it represents an odd piece of global state for a Rust
+program to have. One example of odd behavior that may arise is that if a library
+calls `env::set_exit_status`, then the process is not guaranteed to exit with
+that status (e.g. Rust was called from C).
+
+The purpose of this RFC is to provide at least one method on the path to
+stabilization which will provide a method to exit a process with a nonzero exit
+code.
+
+# Detailed design
+
+The following function will be added to the `std::process` module:
+
+```rust
+/// Terminates the current process with the specified exit code.
+///
+/// This function will never return and will immediately terminate the current
+/// process. The exit code is passed through to the underlying OS and will be
+/// available for consumption by another process.
+///
+/// Note that because this function never returns, and that it terminates the
+/// process, no destructors on the current stack or any other thread's stack
+/// will be run. If a clean shutdown is needed it is recommended to only call
+/// this function at a known point where there are no more destructors left
+/// to run.
+pub fn exit(code: i32) -> !;
+```
+
+Implementation-wise this will correspond to the [`exit` function][unix] on unix
+and the [`ExitProcess` function][win] on windows.
+
+[unix]: http://pubs.opengroup.org/onlinepubs/000095399/functions/exit.html
+[win]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms682658%28v=vs.85%29.aspx
+
+This function is also not marked `unsafe`, despite the risk of leaking
+allocated resources (e.g. destructor smany not be run). It is already possible
+to safely create memory leaks in Rust, however, (with `Rc` + `RefCell`), so
+this is not considered a strong enough threshold to mark the function as
+`unsafe`.
+
+# Drawbacks
+
+* This API does not solve all use cases of exiting with a nonzero exit status.
+  It is sometimes more convenient to simply return a code from the `main`
+  function instead of having to call a separate function in the standard
+  library.
+
+# Alternatives
+
+* One alternative would be to stabilize `set_exit_status` as-is today. The
+  semantics of the function would be clearly documented to prevent against
+  surprises, but it would arguably not prevent all surprises from arising. Some
+  reasons for not pursuing this route, however, have been outlined in the
+  motivation.
+
+* The `main` function of binary programs could be altered to require an
+  `i32` return value. This would greatly lessen the need to stabilize this
+  function as-is today as it would be possible to exit with a nonzero code by
+  returning a nonzero value from `main`. This is a backwards-incompatible
+  change, however.
+
+* The `main` function of binary programs could optionally be typed as `fn() ->
+  i32` instead of just `fn()`. This would be a backwards-compatible change, but
+  does somewhat add complexity. It may strike some as odd to be able to define
+  the `main` function with two different signatures in Rust.
+
+# Unresolved questions
+
+* To what degree should the documentation imply that `rt::at_exit` handlers are
+  run? Implementation-wise their execution is guaranteed, but we may not wish
+  for this to always be so.