class CaptiveThread

True if ForceJoin() or BlockUntilSuccess() has already been called.

Borrow the thread's kernel handle. This handle is valid for the life of

the CaptiveThread object, even after the actual thread dies.

Borrow the handle for the current exception. This handle is only valid

while InException() is true, until ResolveException() is called.

Wait for the thread to get an exception or exit. If this succeeds, then

either InException() is true, or the thread has exited. If the thread is

suspended, this will wait until it resumes and hits an exception or exits.

On success, the result value is just the `this` pointer. This return

value is accepted by the

<lib

/captive-thread/testing/matchers.h> gmock

matchers for `EXPECT_THAT(thread.WaitForException(), ...);` use in tests.

Wait for the thread to be stopped in any fashion. If Suspend() hasn't

been called, then this is similar to WaitForException().

Report if the thread is currently stopped in exception or suspension, or

has a suspension in progress. If Suspend() has been called, then

InSuspend() and IsStopped() are true even if WaitForStop() is still needed

to actually synchronize and be able access registers, etc.

Return the report for the exception, or std::nullopt if !InException().

Create a thread that runs the given function (can be move-only).

This starts a new raw thread made with zx::thread::create(). The

arguments are the initial register values passed to zx::thread::start().

With the optional suspend flag set, Suspend() will be done before the

thread starts (it's still necessary to use WaitForStop() to examine it).

When a "raw" thread is started via CreateRaw() or StartRaw(), it must run

code that's pure assembly or otherwise refrains from any interaction with

normal ABI code or any libc expectations of any kind. If it's allowed to

run to completion, it must use zx_thread_exit() directly. When it's

forcibly "joined", that won't use std::thread::join() or run any normal

C++ or libc thread exit code. Instead, it will force the thread into an

exception state if not already there, and then force it to exit via the

exception handling mechanism.

This is like CreateRaw(), but takes ownership of a zx::thread already

created but not yet started. This allows the thread to be created in some

special fashion (even in another process), or have properties set,

etc. before it starts. To suspend the thread before it starts, pass in an

existing zx::suspend_token for it that's taken over as if from Suspend().

After destruction, the thread is guaranteed to be exited and joined.

If the thread is not already exiting, then force it to exit. Then join

with it as in std::thread::join. Other methods are not necessarily valid

after ForceJoin(), but it is always safe to call ForceJoin() again or to

call ForceJoin() after BlockUntilSuccess().

Request a thread suspension. If it's already stopped in any fashion, this

returns immediate success.

This presumes the thread will finish running the function and waits until

it has done so. If the thread gets an exception, it will not be caught.

Must not be called when IsStopped().

Fetch the thread registers. This caches the value until the next

resumption or SetRegisters(), so it's cheap to call repeatedly.

Modify the thread registers. This clears any values previously cached and

does zx::thread::write_state, so the next Registers

<Regs

>() call will read

the normalized values back with zx::thread::read_state.

Resume and resolve the exception so no other handler will see it. Must be

called when InException() is true.

Resume from being stopped. Must be called when IsStopped() is true. When

InException(), this results in cascading to the next exception handler

(system crash service, etc.).

As above, but resume with single-step enabled.

This is shorthand for ResolveExceptionSingleStep() and WaitForException().