From 2dabd26152745c24cc03e3b4b52b712322b1e8f5 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 24 Mar 2015 17:28:18 -0700 Subject: [PATCH 1/5] RFC: Add std::process::exit Add a new function to the `std::process` module to exit the process immediately with a specified exit code. --- text/0000-process-exit.md | 88 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 text/0000-process-exit.md diff --git a/text/0000-process-exit.md b/text/0000-process-exit.md new file mode 100644 index 00000000000..f801669ac7c --- /dev/null +++ b/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 either 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. From 9b1344bc9ba08c6b2fe112f4b0e1446d43dced09 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 24 Mar 2015 17:31:27 -0700 Subject: [PATCH 2/5] typo --- text/0000-process-exit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-process-exit.md b/text/0000-process-exit.md index f801669ac7c..6e6e239a933 100644 --- a/text/0000-process-exit.md +++ b/text/0000-process-exit.md @@ -70,7 +70,7 @@ this is not considered a strong enough threshold to mark the function as reasons for not pursuing this route, however, have been outlined in the motivation. -* The `main` function of binary programs could be altered to either require an +* 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 From d2e1136b06347cc61108bcdf4f4ee3470286fcd9 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 24 Mar 2015 17:58:22 -0700 Subject: [PATCH 3/5] More typos --- text/0000-process-exit.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-process-exit.md b/text/0000-process-exit.md index 6e6e239a933..1015559ec02 100644 --- a/text/0000-process-exit.md +++ b/text/0000-process-exit.md @@ -50,7 +50,7 @@ and the [`ExitProcess` function][win] on windows. [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 +allocated resources (e.g. destructors may 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`. From d33dd641e965add9a2a8fe3ac52d83dd8f5a3b87 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Wed, 25 Mar 2015 10:36:31 -0700 Subject: [PATCH 4/5] Note that exit() may be desired regarless of main's signature --- text/0000-process-exit.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/text/0000-process-exit.md b/text/0000-process-exit.md index 1015559ec02..bdce352025e 100644 --- a/text/0000-process-exit.md +++ b/text/0000-process-exit.md @@ -79,7 +79,9 @@ this is not considered a strong enough threshold to mark the function as * 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. + the `main` function with two different signatures in Rust. Additionally, it's + likely that the `exit` functionality proposed will be desired regardless of + whether the main function can return a code or not. # Unresolved questions From fc47393ccd8abfe382c94a6b076700ba6091f05f Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 26 Mar 2015 15:46:34 -0700 Subject: [PATCH 5/5] Clarify that exit(0) is ok --- text/0000-process-exit.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-process-exit.md b/text/0000-process-exit.md index bdce352025e..2e078f302ab 100644 --- a/text/0000-process-exit.md +++ b/text/0000-process-exit.md @@ -21,8 +21,8 @@ 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. +stabilization which will provide a method to exit a process with an arbitrary +exit code. # Detailed design