Tracking Issue for `breakpoint` feature (`core::arch::breakpoint`)

[joshtriplett]

Feature gate: #![feature(breakpoint)]

This is a tracking issue for the breakpoint feature, which gates the core::arch::breakpoint function. This feature was approved in ACP 491.

Public API

// core::arch

/// Compiles to a target-specific software breakpoint instruction or equivalent.
///
/// (Long description elided.)
#[inline(always)]
pub fn breakpoint() {
    unsafe {
        core::intrinsics::breakpoint();
    }
}

Steps / History

• ACP: ACP: core::arch::breakpoint libs-team#491
• Implementation: Add core::arch::breakpoint and test #133726
• Final comment period (FCP)¹
• Stabilization PR with lang FCP
  • Stabilize the breakpoint function #142325

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[clarfonthey]

Is there a reason why this is in core::arch instead of core::hint? I feel like it would be logical to say that a perfectly acceptable implementation of this would be to do nothing, and I'd imagine this is what a lot of embedded targets will do.

Plus, core::arch is generally reserved for arch-specific stuff, and this is specifically independent of architecture.

[Scripter17]

Does it really fit in std::hint? Everything else in there is, well, hints to the compiler. Either for lints or for optimization

It fits better in there but it doesn't feel like the obvious place to look for a breakpoint function

[joshtriplett]

@clarfonthey I don't think "do nothing" should be a valid implementation of this. "abort" is a valid implementation. Given that, I don't think this belongs in hint.

That said, that doesn't necessarily make core::arch the best place. It seemed like a good fit at the time, in part because its behavior is arch-specific.

I don't see any existing module that this logically fits in other than arch.

We could put it in a new core::debug or similar, but I'm not sure it's worth a new module for this, and debug could be confused as being related to Debug.

[clarfonthey]

I mean, sure, but we have other things in hint which emit special instructions, like spin_loop. Just because the definition of a "trivial" implementation changes, or that the result is architecture-specific, doesn't mean it doesn't fit into that module.

[joshtriplett]

@clarfonthey AFAICT, every function in core::hint can be replaced by a no-op/identity for a correct (if suboptimal) implementation. I think that's a property worth not losing.

A breakpoint isn't a "hint"; it can't be replaced with a no-op.

Is there any other module in core that you think this could fit into? Or, do you think it's worth creating a new module for this and potential related items?

[kpreid]

JavaScript has the debugger statement which causes the debugger to pause the program if a debugger is available (in current browsers, this means “if the developer tools are open”), and otherwise continues execution. This is a useful behavior (it allows executing an identical program with and without pauses for debugging, without needing to remove the breakpoint and recompile) and if Rust offered it, it would fit in core::hint.

[joshtriplett]

@kpreid I'd love to have that operation, but unfortunately, that's a much more complex operation that isn't as simple as emitting an instruction, it'd be more error-prone (it can erroneously detect a debugger), it'd be less portable (as it's OS-specific rather than CPU-specific), and it wouldn't be available on all targets.

[BrainBacon]

@joshtriplett Maybe an ACP for debugger presence detection? C++ 26 is getting that.

I recently added debugger presence detection to Unbug using the dbg_breakpoint crate. The bulk of that crate was previously accepted as a panic hook in the Rust standard library, but then reverted later.

[joshtriplett]

Stabilization Report

Implementation History

Approved in ACP rust-lang/libs-team#491 , implemented in #133726 , and not modified since. Includes tests and documentation.

Some discussion about what the correct module for this function should be, but no conclusion about a specific better place than core::arch.

API Summary

In core::arch (and thus also std::arch):

pub fn breakpoint();

Experience Report

The ACP was originally inspired by the unbug crate, which was promptly able to switch to this (and will be able to drop some architecture-specific code when this becomes stable, and run on stable Rust on more architectures). https://github.com/microsoft/edit is also using this.

[Amanieu]

@rfcbot merge

[rfcbot]

Team member @Amanieu has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.