Probably not. The ones creating the docs probably have a deep understanding of the language and can no longer see what information people need to understand the issue at hand.
Oof, seems I got the camelcase wrong. It's `@mustuse`
Working on updating that.
I think the reason the documentation is cryptic is because it's a library-supplied User Data Attribute that is specially recognized by the compiler. The documentation generator is having trouble with it. In code it's pretty simple:
If you want to look at it from an academic perspective it tells the compiler that it should be a relevant[1] type. The idea is that you can make the compiler force the use of the value at least once. This is great for error or result types so that you can require the caller of your code actually check for an error or valid result, this way you can't forget to do it (if you do it's a compile error and you never get to run the code).
Thank you, I know it looks stupid simple but code helps me put it into a perspective I can remember better vs only reading documentation about code. That is kind of an interesting way to sort of force someone to not just throw away a return value.
Question: Do you know if this would also be fine if the called function was in a return statement?
This will only cause an error if both of these are true:
- if the expression is the top level expression in a statement (like in my example code) or the left hand side in a comma expression
- if the expression is not an assignment, increment, or decrement
So using it in a return is fine because then the expression is no longer the top level in the statement, the return is. Of course then the function calling THAT function must deal with not discarding the value. It's pretty neat.
> However, a nothrow function is still allowed to throw an Error. How does that work?
> How it works is that the compiler still omits exception cleanup code, and the code that catches the Error is not allowed to continue the program. If it does, the program may obviously be in an invalid state.
Yikes? What's the rationale for allowing errors to be thrown out of nothrow functions, rather than just aborting there and then?
The rationale is that in a correctly written program, an Error should never be thrown. It's similar to UB in C. The compiler can assume Errors are never thrown, and so it can not worry about cleanup in nothrow functions.
But the nice thing is, it reuses the same handling mechanisms as exceptions. You don't have to create something different for handling Errors. In fact, the code that prints error stack traces and exits is the same code that handles exceptions.
Consequently, this is why you shouldn't catch them, or at least not catch them and continue. The exceptions are unittests and contract asserts, where the compiler does guarantee proper stack unwinding.
> The rationale is that in a correctly written program, an Error should never be thrown. [...] you shouldn't catch them, or at least not catch them and continue
In that case, why not just abort? Why give the user a footgun like this?
FWIW, C++'s noexcept specifier turns exceptions into aborts rather than letting them escape [1]:
> Non-throwing functions are permitted to call potentially-throwing functions. Whenever an exception is thrown and the search for a handler encounters the outermost block of a non-throwing function, the function std::terminate or std::unexpected (until C++17) is called:
Microsoft's dialect of C++ has a nothrow attribute which is purely advisory, like D's, and is now deprecated in favour of noexcept [2]:
> We recommend that all new code use the noexcept operator rather than __declspec(nothrow).
> This attribute tells the compiler that the declared function and the functions it calls never throw an exception. However, it does not enforce the directive. In other words, it never causes std::terminate to be invoked, unlike noexcept, or in std:c++17 mode (Visual Studio 2017 version 15.5 and later), throw().
Rust has panics, which by default unwind, like exceptions, but can be compiled to abort instead [3]:
> By default, when a panic occurs, the program starts unwinding, which means Rust walks back up the stack and cleans up the data from each function it encounters. However, this walking back and cleanup is a lot of work. Rust, therefore, allows you to choose the alternative of immediately aborting, which ends the program without cleaning up.
I don't believe there is any stable or planned way to declare that normal Rust functions cannot panic (so should abort instead of letting the panic escape). But there is some work towards the idea that extern "C" functions should do so [4].
24 comments
[ 3.0 ms ] story [ 65.8 ms ] thread[0] https://dlang.org/library/core/attribute/mustuse.html
https://en.cppreference.com/w/cpp/language/attributes/nodisc...
https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attribute...
I can fix it but the example given is clear, no?
Working on updating that.
I think the reason the documentation is cryptic is because it's a library-supplied User Data Attribute that is specially recognized by the compiler. The documentation generator is having trouble with it. In code it's pretty simple:
https://github.com/dlang/druntime/blob/705fb36e5fc4d930eed85...
e.g. if you return something that could contain an error then ignoring the return value could be disastrous.
https://github.com/bminor/glibc/search?q=__wur&type=
[1] https://en.wikipedia.org/wiki/Substructural_type_system#Diff...
Question: Do you know if this would also be fine if the called function was in a return statement?
- if the expression is the top level expression in a statement (like in my example code) or the left hand side in a comma expression - if the expression is not an assignment, increment, or decrement
So using it in a return is fine because then the expression is no longer the top level in the statement, the return is. Of course then the function calling THAT function must deal with not discarding the value. It's pretty neat.
> How it works is that the compiler still omits exception cleanup code, and the code that catches the Error is not allowed to continue the program. If it does, the program may obviously be in an invalid state.
Yikes? What's the rationale for allowing errors to be thrown out of nothrow functions, rather than just aborting there and then?
But the nice thing is, it reuses the same handling mechanisms as exceptions. You don't have to create something different for handling Errors. In fact, the code that prints error stack traces and exits is the same code that handles exceptions.
Consequently, this is why you shouldn't catch them, or at least not catch them and continue. The exceptions are unittests and contract asserts, where the compiler does guarantee proper stack unwinding.
In that case, why not just abort? Why give the user a footgun like this?
> Non-throwing functions are permitted to call potentially-throwing functions. Whenever an exception is thrown and the search for a handler encounters the outermost block of a non-throwing function, the function std::terminate or std::unexpected (until C++17) is called:
Microsoft's dialect of C++ has a nothrow attribute which is purely advisory, like D's, and is now deprecated in favour of noexcept [2]:
> We recommend that all new code use the noexcept operator rather than __declspec(nothrow).
> This attribute tells the compiler that the declared function and the functions it calls never throw an exception. However, it does not enforce the directive. In other words, it never causes std::terminate to be invoked, unlike noexcept, or in std:c++17 mode (Visual Studio 2017 version 15.5 and later), throw().
Rust has panics, which by default unwind, like exceptions, but can be compiled to abort instead [3]:
> By default, when a panic occurs, the program starts unwinding, which means Rust walks back up the stack and cleans up the data from each function it encounters. However, this walking back and cleanup is a lot of work. Rust, therefore, allows you to choose the alternative of immediately aborting, which ends the program without cleaning up.
I don't believe there is any stable or planned way to declare that normal Rust functions cannot panic (so should abort instead of letting the panic escape). But there is some work towards the idea that extern "C" functions should do so [4].
[1] https://en.cppreference.com/w/cpp/language/noexcept_spec
[2] https://docs.microsoft.com/en-us/cpp/cpp/nothrow-cpp?view=ms...
[3] https://doc.rust-lang.org/book/ch09-01-unrecoverable-errors-...
[4] https://github.com/rust-lang/project-ffi-unwind/blob/master/...