lang | libs (syntax | expressions | error-handling)
Allow the ? operator to be used in main, and in #[test]
functions and doctests.
To make this possible, the return type of these functions are
generalized from () to a new trait, provisionally called
Termination. libstd implements this trait for a set of types
partially TBD (see list below);
applications can provide impls themselves if they want.
There is no magic added to function signatures in rustc. If you want
to use ? in either main or a #[test] function you have to write
-> Result<(), ErrorT> (or whatever) yourself. Initially, it will
also be necessary to write a hidden function head for any doctest that
wants to use ?, but eventually (see the
deployment plan below) the default doctest
template will be adjusted to make this unnecessary most of the time.
Pre-RFC discussion. Prior RFC issue.
It is currently not possible to use ? in main, because main's
return type is required to be (). This is a trip hazard for new
users of the language, and complicates "programming in the small".
For example, consider a version of the
CSV-parsing example from the Rust Book
(I have omitted a chunk of command-line parsing code and the
definition of the Row type, to keep it short):
fn main() {
let argv = env::args();
let _ = argv.next();
let data_path = argv.next().unwrap();
let city = argv.next().unwrap();
let file = File::open(data_path).unwrap();
let mut rdr = csv::Reader::from_reader(file);
for row in rdr.decode::<Row>() {
let row = row.unwrap();
if row.city == city {
println!("{}, {}: {:?}",
row.city, row.country,
row.population.expect("population count"));
}
}
}
The Rust Book uses this as a starting point for a demonstration of how
to do error handing properly, i.e. without using unwrap and
expect. But suppose this is a program for your own personal use.
You are only writing it in Rust because it needs to crunch an enormous
data file and high-level scripting languages are too slow. You don't
especially care about proper error handling, you just want something
that works, with minimal programming effort. You'd like to not have
to remember that this is main and you can't use ?. You would like
to write instead
fn main() -> Result<(), Box<Error>> {
let argv = env::args();
let _ = argv.next();
let data_path = argv.next()?;
let city = argv.next()?;
let file = File::open(data_path)?;
let mut rdr = csv::Reader::from_reader(file);
for row in rdr.decode::<Row>() {
let row = row?;
if row.city == city {
println!("{}, {}: {:?}",
row.city, row.country, row.population?);
}
}
Ok(())
}
(Just to be completely clear, this is not intended to reduce the
amount of error-handling boilerplate one has to write; only to make it
be the same in main as it would be for any other function.)
For the same reason, it is not possible to use ? in doctests and
#[test] functions. This is only an inconvenience for #[test]
functions, same as for main, but it's a major problem for doctests,
because doctests are supposed to demonstrate normal usage, as well as
testing functionality. Taking an
example from the stdlib:
use std::net::UdpSocket;
let port = 12345;
let mut udp_s = UdpSocket::bind(("127.0.0.1", port)).unwrap(); // XXX
udp_s.send_to(&[7], (ip, 23451)).unwrap(); // XXX
The lines marked XXX have to use unwrap, because a doctest is the
body of a main function, but in normal usage, they would be written
let mut udp_s = UdpSocket::bind(("127.0.0.1", port))?;
udp_s.send_to(&[7], (ip, 23451))?;
and that's what the documentation ought to say. Documentation
writers can work around this by including their own main as
hidden code, but they shouldn't have to.
On a related note, main returning () means that short-lived
programs, designed to be invoked from the Unix shell or a similar
environment, have to contain extra boilerplate in order to comply with
those environments' conventions, and must ignore the dire warnings
about destructors not getting run in the documentation for
process::exit. (In particular, one might be
concerned that the program below will not properly flush and close
io::stdout, and/or will fail to detect delayed write failures on
io::stdout.) A typical construction is
fn inner_main() -> Result<(), ErrorT> {
// ... stuff which may fail ...
Ok(())
}
fn main() -> () {
use std::process::exit;
use libc::{EXIT_SUCCESS, EXIT_FAILURE};
exit(match inner_main() {
Ok(_) => EXIT_SUCCESS,
Err(ref err) => {
let progname = get_program_name();
eprintln!("{}: {}\n", progname, err);
EXIT_FAILURE
}
})
}
These problems can be solved by generalizing the return type of main
and test functions.
The design goals for this new feature are, in decreasing order of importance:
? operator should be usable in main, #[test] functions,
and doctests. This entails these functions now returning a richer
value than ().fn main() -> () should not break.main in a hosted environment should
not trigger a panic, consistent with the general language
principle that panics are only for bugs.Goal 1 dictates that the new return type for main will be
Result<T, E> for some T and E. To minimize the necessary changes to
existing code that wants to start using ? in main, T should be
allowed to be (), but other types in that position may also make
sense. The appropriate bound for E is unclear; there are plausible
arguments for at least Error, Debug, and Display. This proposal
selects Display, largely because application error types are not
obliged to implement Error.
To achieve goal 2 at the same time as goal 1, main's return type
must be allowed to vary from program to program. This can be dealt
with by making the start lang item polymorphic (as
described below) over a
trait which both () and Result<(), E> implement, and similarly for
doctests and
#[test] functions.
Goals 3 and 4 are largely a matter of quality of implementation; at
the level of programmer-visible interfaces, people who don't care are
well-served by not breaking existing code (which is goal 2) and by
removing a way in which main is not like other functions (goal 1).
Termination traitWhen main returns a nontrivial value, the runtime needs to know two
things about it: what error message, if any, to print, and what value
to pass to std::process::exit. These are naturally encapsulated in
a trait, which we are tentatively calling Termination, with this
signature:
trait Termination {
fn report(self) -> i32;
}
report is a call-once function; it consumes self. The runtime
guarantees to call this function after main returns, but at a point
where it is still safe to use eprintln! or io::stderr() to print
error messages. report is not required to print error messages,
and if it doesn't, nothing will be printed. The value it returns will
be passed to std::process::exit, and shall convey at least a notion
of success or failure. The return type is i32 to match
std::process::exit (which probably calls the C library's exit
primitive), but (as already documented for process::exit) on "most
Unix-like" operating systems, only the low 8 bits of this value are
significant.
At least the following implementations of Termination will be added to
libstd. (Code samples below use the constants EXIT_SUCCESS and
EXIT_FAILURE for exposition;
see below for discussion of
what the actual numeric values should be.) The first two are
essential to the proposal:
impl Termination for () {
fn report(self) -> i32 { EXIT_SUCCESS }
}
This preserves backward compatibility: all existing programs, with
fn main() -> (), will still satisfy the new requirement (which is
effectively fn main() -> impl Termination, although the proposal
does not actually depend on impl-trait return types).
impl<T: Termination, E: Display> Termination for Result<T, E> {
fn report(self) -> i32 {
match self {
Ok(val) => val.report(),
Err(ref err) => {
print_diagnostics_for_error(err);
EXIT_FAILURE
}
}
}
}
This enables the use of ? in main. The type bound is somewhat
more general than the minimum: we accept any type that satisfies
Termination in the Ok position, not just (). This is because, in
the presence of application impls of Termination, it would be
surprising if fn main() -> FooT was acceptable but fn main() -> Result<FooT, ErrT> wasn't, or vice versa. On the Err side, any
displayable type is acceptable, but its value does not affect the exit
status; this is because it would be surprising if an apparent error
return could produce a successful exit status. (This restriction can
always be relaxed later.)
Note that Box<T> is Display if T is Display, so special treatment of
Box<Error> is not necessary.
Two additional impls are not strictly necessary, but are valuable for concrete known usage scenarios:
impl Termination for ! {
fn report(self) -> i32 { unreachable!(); }
}
This allows programs that intend to run forever to be more
self-documenting: fn main() -> ! will satisfy the bound on main's
return type. It might not be necessary to have code for this impl in
libstd, since -> ! satisfies -> (), but it should appear in the
reference manual anyway, so people know they can do that, and it may
be desirable to include the code as a backstop against a main that
does somehow return, despite declaring that it doesn't.
impl Termination for bool {
fn report(self) -> i32 {
if (self) { EXIT_SUCCESS } else { EXIT_FAILURE }
}
}
This impl allows programs to generate both success and failure
conditions for their outer environment without printing any
diagnostics, by returning the appropriate values from main, possibly
while also using ? to report error conditions where diagnostics
should be printed. It is meant to be used by sophisticated programs
that do all, or nearly all, of their own error-message printing
themselves, instead of calling process::exit themselves.
The detailed behavior of print_diagnostics_for_error is left
unspecified, but it is guaranteed to write diagnostics to io::stderr
that include the Display text for the object it is passed, and
without unconditionally calling panic!. When the object it is
passed implements Error as well as Display, it should follow the
cause chain if there is one (this may necessitate a separate
Termination impl for Result<_, Error>, but that's an implementation
detail).
lang_startThe start "lang item", the function that calls main, takes the
address of main as an argument. Its signature is currently
#[lang = "start"]
fn lang_start(main: *const u8, argc: isize, argv: *const *const u8) -> isize
It will need to become generic, something like
#[lang = "start"]
fn lang_start<T: Termination>
(main: fn() -> T, argc: isize, argv: *const *const u8) -> !
(Note: the current isize return type is incorrect. As is, the
correct return type is libc::c_int. We can avoid the entire issue by
requiring lang_start to call process::exit or equivalent itself;
this also moves one step toward not depending on the C runtime.)
The implementation for typical "hosted" environments will be something like
#[lang = "start"]
fn lang_start<T: Termination>
(main: fn() -> T, argc: isize, argv: *const *const u8) -> !
{
use panic;
use sys;
use sys_common;
use sys_common::thread_info;
use thread::Thread;
sys::init();
sys::process::exit(unsafe {
let main_guard = sys::thread::guard::init();
sys::stack_overflow::init();
// Next, set up the current Thread with the guard information we just
// created. Note that this isn't necessary in general for new threads,
// but we just do this to name the main thread and to give it correct
// info about the stack bounds.
let thread = Thread::new(Some("main".to_owned()));
thread_info::set(main_guard, thread);
// Store our args if necessary in a squirreled away location
sys::args::init(argc, argv);
// Let's run some code!
let exitcode = panic::catch_unwind(|| main().report())
.unwrap_or(101);
sys_common::cleanup();
exitcode
});
}
Simple doctests form the body of a main function, so they require
only a small modification to rustdoc: when maketest sees that it
needs to insert a function head for main, it will now write out
fn main () -> Result<(), ErrorT> {
...
Ok(())
}
for some value of ErrorT to be worked out
during deployment. This head will work correctly
for function bodies without any uses of ?, so rustdoc does not need
to parse each function body; it can use this head unconditionally.
If the doctest specifies its own function head for main (visibly or
invisibly), then it is the programmer's responsibility to give it an
appropriate type signature, as for regular main.
#[test] harnessThe appropriate semantics for test functions with rich return values
are straightforward: Call the report method on the value returned.
If report returns a nonzero value, the test has failed.
(Optionally, honor the Automake convention that exit code 77 means
"this test cannot meaningfully be run in this context.")
The required changes to the test harness are more complicated, because it supports six different type signatures for test functions:
pub enum TestFn {
StaticTestFn(fn()),
StaticBenchFn(fn(&mut Bencher)),
StaticMetricFn(fn(&mut MetricMap)),
DynTestFn(Box<FnBox<()>>),
DynMetricFn(Box<for<'a> FnBox<&'a mut MetricMap>>),
DynBenchFn(Box<TDynBenchFn + 'static>),
}
All of these need to be generalized to allow any return type that implements Termination. At the same time, it still needs to be possible to put TestFn instances into a static array.
For the static cases, we can avoid changing the test harness at all with a built-in macro that generates wrapper functions: for example, given
#[test]
fn test_the_thing() -> Result<(), io::Error> {
let state = setup_the_thing()?; // expected to succeed
do_the_thing(&state)?; // expected to succeed
}
#[bench]
fn bench_the_thing(b: &mut Bencher) -> Result<(), io::Error> {
let state = setup_the_thing()?;
b.iter(|| {
let rv = do_the_thing(&state);
assert!(rv.is_ok(), "do_the_thing returned {:?}", rv);
});
}
after macro expansion we would have
fn test_the_thing_inner() -> Result<(), io::Error> {
let state = setup_the_thing()?; // expected to succeed
do_the_thing(&state)?; // expected to succeed
}
#[test]
fn test_the_thing() -> () {
let rv = test_the_thing_inner();
assert_eq!(rv.report(), 0);
}
fn bench_the_thing_inner(b: &mut Bencher) -> Result<(), io::Error> {
let state = setup_the_thing()?;
b.iter(|| {
let rv = do_the_thing(&state);
assert!(rv.is_ok(), "do_the_thing returned {:?}", rv);
});
}
#[bench]
fn bench_the_thing(b: &mut Bencher) -> () {
let rv = bench_the_thing_inner();
assert_eq!(rv.report(), 0);
}
and similarly for StaticMetricFn (no example shown because I cannot find any actual uses of MetricMap anywhere in the stdlib, so I don't know what a use looks like).
We cannot synthesize wrapper functions like this for dynamic tests.
We could use trait objects to allow the harness to call
Termination::report anyway: for example, assuming that
runtest::run returns a Termination type, we would have something
like
pub fn make_test_closure(config: &Config, testpaths: &TestPaths)
-> test::TestFn {
let config = config.clone();
let testpaths = testpaths.clone();
test::DynTestFn(Box::new(move |()| -> Box<Termination> {
Box::new(runtest::run(config, &testpaths))
}))
}
But this is not that much of an improvement on just checking the result inside the closure:
pub fn make_test_closure(config: &Config, testpaths: &TestPaths)
-> test::TestFn {
let config = config.clone();
let testpaths = testpaths.clone();
test::DynTestFn(Box::new(move |()| {
let rv = runtest::run(config, &testpaths);
assert_eq(rv.report(), 0);
}))
}
Considering also that dynamic tests are not documented and rarely used (the only cases I can find in the stdlib are as an adapter mechanism within libtest itself, and the compiletest harness) I think it makes most sense to not support rich return values from dynamic tests for now.
main in nostd environmentsSome no-std environments do have a notion of processes that run and
then exit, but do not have a notion of "exit status". In this case,
process::exit probably already ignores its argument, so main and
the start lang item do not need to change. Similarly, in an
environment where there is no such thing as an "error message",
io::stderr() probably already points to the bit bucket, so report
functions can go ahead and use eprintln! anyway.
There are also environments where
returning from main constitutes a bug. If you
are implementing an operating system kernel, for instance, there may
be nothing to return to. Then you want it to be a compile-time error
for main to return anything other than !. If everything is
implemented correctly, such environments should be able to get that
effect by omitting all stock impls of Termination other than for
!. Perhaps there should also be a compiler hook that allows such
environments to refuse to let you impl Termination yourself.
EXIT_SUCCESS and EXIT_FAILURE by standard impls of TerminationThe C standard only specifies 0, EXIT_SUCCESS and EXIT_FAILURE
as arguments to the exit primitive. It does not require
EXIT_SUCCESS to be zero, but it does require exit(0) to have the
same effect as exit(EXIT_SUCCESS). POSIX does require
EXIT_SUCCESS to be zero, and the only historical C implementation I
am aware of where EXIT_SUCCESS was not zero was for VAX/VMS, which
is probably not a relevant portability target for Rust.
EXIT_FAILURE is only required (implicitly in C, explicitly in POSIX)
to be nonzero. It is usually 1; I have not done a thorough survey
to find out if it is ever anything else.
Within both the Unix and Windows ecosystems, there are several
different semi-conflicting conventions that assign meanings to
specific nonzero exit codes. It might make sense to include some
support for these conventions in the stdlib (e.g. with a module that
provides the same constants as sysexits.h), but that is
beyond the scope of this RFC. What is important, in the context of
this RFC, is for the standard impls of Termination to not get in the
way of any program that wants to use one of those conventions.
Therefore I am proposing that all the standard impls' report
functions should use 0 for success and 2 for failure. (It is
important not to use 1, even though EXIT_FAILURE is usually 1,
because some existing programs (notably grep) give 1 a
specific meaning; as far as I know, 2 has no specific meaning
anywhere.)
This is a complicated feature; it needs two mostly-orthogonal feature gates and a multi-phase deployment sequence.
The first feature gate is #![feature(rich_main_return)], which must
be enabled to write a main function, test function, or doctest that
returns something other than (). This is not a normal unstable-feature
annotation; it has more in common with a lint check and may need to be
implemented as such. It will probably be possible to stabilize this
feature quickly—one or two releases after it is initially implemented.
The second feature gate is #![feature(termination_trait)], which
must be enabled to make explicit use of the Termination trait,
either by writing new impls of it, or by calling report directly.
However, it is not necessary to enable this feature gate to merely
return rich values from main, test functions, etc (because in that
case the call to report is in stdlib code). I think this is the
semantic of an ordinary unstable-feature annotation on Termination,
with appropriate use-this annotations within the stdlib. This feature
should not be stabilized for at least a full release after the
stabilization of the rich_main_return feature, because it has more
complicated backward compatibility implications, and because it's not
going to be used very often so it will take longer to gain experience
with it.
In addition to these feature gates, rustdoc will initially not change
its template for main. In order to use ? in a doctest, at first
it will be necessary for the doctest to specify its own function head.
For instance, the ToSocketAddrs example from the
"motivation" section will initially need to be written
/// # #![feature(rich_main_return)]
/// # fn main() -> Result<(), io::Error> {
/// use std::net::UdpSocket;
/// let port = 12345;
/// let mut udp_s = UdpSocket::bind(("127.0.0.1", port))?;
/// udp_s.send_to(&[7], (ip, 23451))?;
/// # Ok(())
/// # }
After enough doctests have been updated, we can survey them to learn
what the most appropriate default function signature for doctest
main is, and only then should rustdoc's template be changed.
(Ideally, this would happen at the same time that rich_main_return
is stabilized, but it might need to wait longer, depending on how
enthusiastic people are about changing their doctests.)
This should be taught alongside the ? operator and error handling in
general. The stock Termination impls in libstd mean that simple
programs that can fail don't need to do anything special.
fn main() -> Result<(), io::Error> {
let mut stdin = io::stdin();
let mut raw_stdout = io::stdout();
let mut stdout = raw_stdout.lock();
for line in stdin.lock().lines() {
stdout.write(line?.trim().as_bytes())?;
stdout.write(b"\n")?;
}
stdout.flush()
}
Programs that care about the exact structure of their error messages
will still need to use main primarily for error reporting.
Returning to the CSV-parsing example, a "professional"
version of the program might look something like this (assume all of
the boilerplate involved in the definition of AppError is just off
the top of your screen; also assume that impl Termination for bool
is available):
struct Args {
progname: String,
data_path: PathBuf,
city: String
}
fn parse_args() -> Result<Args, AppError> {
let argv = env::args_os();
let progname = argv.next().into_string()?;
let data_path = PathBuf::from(argv.next());
let city = argv.next().into_string()?;
if let Some(_) = argv.next() {
return Err(UsageError("too many arguments"));
}
Ok(Args { progname, data_path, city })
}
fn process(city: &String, data_path: &Path) -> Result<Args, AppError> {
let file = File::open(args.data_path)?;
let mut rdr = csv::Reader::from_reader(file);
for row in rdr.decode::<Row>() {
let row = row?;
if row.city == city {
println!("{}, {}: {:?}",
row.city, row.country, row.population?);
}
}
}
fn main() -> bool {
match parse_args() {
Err(err) => {
eprintln!("{}", err);
false
},
Ok(args) => {
match process(&args.city, &args.data_path) {
Err(err) => {
eprintln!("{}: {}: {}",
args.progname, args.data_path, err);
false
},
Ok(_) => true
}
}
}
}
and a detailed error-handling tutorial could build that up from the
quick-and-dirty version. Notice that this is not using ? in main,
but it is using the generalized main return value. The
catch-block feature (part of RFC #243 along with ?;
issue #39849) may well enable shortening this main
and/or putting parse_args and process back inline.
Tutorial examples should still begin with fn main() -> () until the
tutorial gets to the point where it starts explaining why panic! and
unwrap are not for "normal errors". The Termination trait should
also be explained at that point, to illuminate how Results
returned from main turn into error messages and exit statuses, but
as a thing that most programs will not need to deal with directly.
Once the doctest default template is changed, doctest examples can
freely use ? with no extra boilerplate, but #[test] examples
involving ? will need their boilerplate adjusted.
Generalizing the return type of main complicates libstd and/or the
compiler. It also adds an additional thing to remember when complete
newbies to the language get to error handling. On the other hand,
people coming to Rust from other languages may find this less
surprising than the status quo.
Do nothing; continue to live with the trip hazard, the extra
boilerplate required to comply with platform conventions, and people
using panic! to report ordinary errors because it's less hassle.
"Template projects" (e.g. quickstart) mean that one need not write
out all the boilerplate by hand, but it's still there.
We need to decide what to call the new trait. The names proposed in
the pre-RFC thread were Terminate, which I like OK but have changed
to Termination because value traits should be nouns, and Fallible,
which feels much too general, but could be OK if there were other uses
for it? Relatedly, it is conceivable that there are other uses for
Termination in the existing standard library, but I can't think of
any right now. (Thread join was mentioned in the pre-RFC,
but that can already relay anything that's Send, so I don't see that
it adds value there.)
We may discover during the deployment process that we want more impls
for Termination. The question of what type rustdoc should use for
its default main template is explicitly deferred till during
deployment.
Some of the components of this proposal may belong in libcore, but
note that the start lang item is not in libcore. It should not be a
problem to move pieces from libstd to libcore later.
It would be nice if we could figure out a way to enable use of ? in
dynamic test-harness tests, but I do not think this is an urgent problem.
All of the code samples in this RFC need to be reviewed for correctness and proper use of idiom.
This proposal formerly included changes to process::ExitStatus
intended to make it usable as a main return type. That has now been
spun off as its own pre-RFC, so that we can take our
time to work through the portability issues involved with going beyond
C's simple success/failure dichotomy without holding up this project.
There is an outstanding proposal to generalize ?
(see also RFC issues #1718 and #1859); I
think it is mostly orthogonal to this proposal, but we should make
sure it doesn't conflict and we should also figure out whether we
would need more impls of Termination to make them play well
together.
There is also an outstanding proposal to improve the ergonomics of
?-using functions by
autowrapping fall-off-the-end return values in Ok;
it would play well with this proposal, but is not necessary nor does
it conflict.