update docs for `catch_unwind` & related funcs · qinheping/verify-rust-std@35edcb6 (original) (raw)

`@@ -285,45 +285,55 @@ where

285

286

`/// Invokes a closure, capturing the cause of an unwinding panic if one occurs.

287

`///

288

`` -

/// This function will return Ok with the closure's result if the closure

289

`` -

/// does not panic, and will return Err(cause) if the closure panics. The

290

`` -

/// cause returned is the object with which panic was originally invoked.

288

`` +

/// This function will return Ok with the closure's result if the closure does

289

`` +

/// not panic, and will return Err(cause) if the closure panics. The cause

290

/// returned is the object with which panic was originally invoked.

291

`///

292

/// It is currently undefined behavior to unwind from Rust code into foreign

293

/// code, so this function is particularly useful when Rust is called from

294

/// another language (normally C). This can run arbitrary Rust code, capturing a

295

/// panic and allowing a graceful handling of the error.

292

/// Rust functions that are expected to be called from foreign code that does

293

`` +

/// not support unwinding (such as C compiled with -fno-exceptions) should be

294

`` +

/// defined using extern "C", which ensures that if the Rust code panics, it

295

/// is automatically caught and the process is aborted. If this is the desired

296

`` +

/// behavior, it is not necessary to use catch_unwind explicitly. This

297

/// function should instead be used when more graceful error-handling is needed.

296

298

`///

297

299

`/// It is not recommended to use this function for a general try/catch

298

300

`` /// mechanism. The [Result] type is more appropriate to use for functions that

299

301

`/// can fail on a regular basis. Additionally, this function is not guaranteed

300

302

`/// to catch all panics, see the "Notes" section below.

301

303

`///

302

`` -

/// The closure provided is required to adhere to the [UnwindSafe] trait to ensure

303

/// that all captured variables are safe to cross this boundary. The purpose of

304

/// this bound is to encode the concept of [exception safety][rfc] in the type

305

/// system. Most usage of this function should not need to worry about this

306

`` -

/// bound as programs are naturally unwind safe without unsafe code. If it

307

`` -

/// becomes a problem the [AssertUnwindSafe] wrapper struct can be used to quickly

308

/// assert that the usage here is indeed unwind safe.

304

`` +

/// The closure provided is required to adhere to the [UnwindSafe] trait to

305

/// ensure that all captured variables are safe to cross this boundary. The

306

/// purpose of this bound is to encode the concept of [exception safety][rfc] in

307

/// the type system. Most usage of this function should not need to worry about

308

`` +

/// this bound as programs are naturally unwind safe without unsafe code. If

309

`` +

/// it becomes a problem the [AssertUnwindSafe] wrapper struct can be used to

310

/// quickly assert that the usage here is indeed unwind safe.

309

311

`///

310

312

`/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md

311

313

`///

312

314

`/// # Notes

313

315

`///

314

/// Note that this function might not catch all panics in Rust. A panic in

315

/// Rust is not always implemented via unwinding, but can be implemented by

316

/// aborting the process as well. This function only catches unwinding panics,

317

/// not those that abort the process.

316

/// This function might not catch all Rust panics. A Rust panic is not

317

/// always implemented via unwinding, but can be implemented by aborting the

318

/// process as well. This function only catches unwinding panics, not those

319

/// that abort the process.

318

320

`///

319

/// Note that if a custom panic hook has been set, it will be invoked before

320

/// the panic is caught, before unwinding.

321

/// If a custom panic hook has been set, it will be invoked before the panic is

322

/// caught, before unwinding.

321

323

`///

322

/// Also note that unwinding into Rust code with a foreign exception (e.g.

323

/// an exception thrown from C++ code) is undefined behavior.

324

/// Although unwinding into Rust code with a foreign exception (e.g. an

325

`` +

/// exception thrown from C++ code, or a panic! in Rust code compiled or

326

`` +

/// linked with a different runtime) via an appropriate ABI (e.g. "C-unwind")

327

/// is permitted, catching such an exception using this function will have one

328

/// of two behaviors, and it is unspecified which will occur:

324

329

`///

325

/// Finally, be careful in how you drop the result of this function.

326

`` -

/// If it is Err, it contains the panic payload, and dropping that may in turn panic!

330

`` +

/// * The process aborts, after executing all destructors of f and the

331

/// functions it called.

332

`` +

/// * The function returns a Result::Err containing an opaque type.

333

///

334

/// Finally, be careful in how you drop the result of this function. If it

335

`` +

/// is Err, it contains the panic payload, and dropping that may in turn

336

/// panic!

327

337

`///

328

338

`/// # Examples

329

339

`///

update docs for catch_unwind & related funcs · qinheping/verify-rust-std@35edcb6 (original) (raw)

update docs for `catch_unwind` & related funcs · qinheping/verify-rust-std@35edcb6 (original) (raw)