Open Bug 1046800 Opened 7 years ago Updated 7 years ago

Unreachability macro documentation is confusing (MOZ_ASSERT_UNREACHABLE and MOZ_MAKE_COMPILER_BELIEVE_IS_UNREACHABLE)

Categories

(Core :: MFBT, defect)

defect
Not set
normal

Tracking

()

People

(Reporter: froydnj, Unassigned)

References

Details

We have:

/*
 * MOZ_ASSUME_UNREACHABLE_MARKER() expands to an expression which states that
 * it is undefined behavior for execution to reach this point.  No guarantees
 * are made about what will happen if this is reached at runtime.  Most code
 * should use MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE because it has extra
 * asserts.
 */

I don't think people should really be using MOZ_ASSUME_UNREACHABLE_MARKER; they probably want MOZ_ASSERT_UNREACHABLE.  But if we assume that we were supposed to s/MOZ_ASSUME_UNREACHABLE_MARKER/MOZ_ASSERT_UNREACHABLE/ in the above, then we are led to think that we should be using MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE, whose documentation states:

 * In Gecko, you probably should not use this macro outside of performance- or
 * size-critical code, because it's unsafe.  If you don't care about code size
 * or performance, you should probably use MOZ_ASSERT or MOZ_CRASH.

From a Gecko hacker's perspective, this documentation is weird, because I was informed MOZ_MAKE_COMPILER_ASSUME_IS_UNREACHABLE had extra asserts.  But the documentation explicitly says it's unsafe!  And then it points me to MOZ_ASSERT/MOZ_CRASH, which presumably aren't explicit enough for what I want to do.

Something needs to be straightened out here.
MOZ_ASSUME_UNREACHABLE_MARKER is an implementation detail of MOZ_MAKE_COMPILER_BELIEVE_IS_UNREACHABLE and should not be called outside of mfbt/Assertions.h.

MOZ_MAKE_COMPILER_BELIEVE_IS_UNREACHABLE includes extra asserts in debug builds, but this macro is intended to be an compiler-specific optimization hint. New code should use:

* MOZ_ASSERT_UNREACHABLE for code that can safely recover in release builds
* MOZ_CRASH for code that can't recover or indicates a major bug
* MOZ_MAKE_COMPILER_BELIEVE_IS_UNREACHABLE to invoke compiler-specific optimizations with undefined behavior
Depends on: 990764
Summary: unreachability macro documentation is confusing → Unreachability macro documentation is confusing (MOZ_ASSERT_UNREACHABLE and MOZ_MAKE_COMPILER_BELIEVE_IS_UNREACHABLE)
You need to log in before you can comment on or make changes to this bug.