POF definition & links

Author: Kyle Strand

rfcs/0000-c-unwind-abi.md

@@ -16,6 +16,10 @@ Additionally, we define the behavior for a limited number of
 previously-undefined cases when an unwind operation reaches a Rust function
 boundary with a non-`"Rust"`, non-`"C unwind"` ABI.
 
+As part of this specification, we introduce the term ["Plain Old Frame"
+(POF)][POF-definition]. These are frames that may be safely deallocated with
+`longjmp`.
+
 This RFC does not define the behavior of `catch_unwind` in a Rust frame being
 unwound by a foreign exception. This is something the [project
 group][project-group] would like to specify in a future RFC; as such, it is
@@ -36,8 +40,8 @@ native exception mechanisms in GCC, LLVM, and MSVC.
 Additionally, there are libraries such as `rlua` that rely on `longjmp` across
 Rust frames; on Windows, `longjmp` is implemented via [forced
 unwinding][forced-unwinding]. The current `rustc` implementation makes it safe
-to `longjmp` across Rust frames without `Drop` types, but this is not formally
-specified in an RFC or by the Reference.
+to `longjmp` across Rust [POFs][POF-definition] (frames without `Drop` types),
+but this is not formally specified in an RFC or by the Reference.
 
 The desire for this feature has been previously discussed on other RFCs,
 including [#2699][rfc-2699] and [#2753][rfc-2753].
@@ -74,8 +78,8 @@ how well the current design satisfies these constraints.
 * **Enable error handling with `longjmp`:** As mentioned above, some existing
   Rust libraries use `longjmp`. Despite the fact that `longjmp` on Windows is
   [technically a form of unwinding][forced-unwinding], using `longjmp` across
-  Rust frames [is safe][longjmp-pr] with the current implementation of `rustc`,
-  and we want to specify that this will remain safe.
+  Rust [POFs][POF-definition] [is safe][longjmp-pr] with the current
+  implementation of `rustc`, and we want to specify that this will remain safe.
 * **Do not change the ABI of functions in the `libc` crate:** Some `libc`
   functions may invoke `pthread_exit`, which uses [a form of
   unwinding][forced-unwinding] in the GNU libc implementation. Such functions
@@ -126,6 +130,28 @@ may be "sandwiched" between Rust frames, so that Rust `panic`s may safely
 unwind the C++ frames, if the Rust code declares both the C++ entrypoint and
 the Rust entrypoint using `"C unwind"`.
 
+## "Plain Old Frames"
+[POF-definition]: #plain-old-frames
+
+A "POF", or "Plain Old Frame", is defined as a frame that can be trivially
+deallocated; that is, returning from or unwinding a POF cannot cause any
+observable effects. This means that POFs do not contain any pending destructors
+(live `Drop` objects) or `catch_unwind` calls.
+
+The terminology is intentionally akin to [C++'s "Plain Old Data"
+types][cpp-POD-definition], which are types that, among other requirements, are
+trivially destructible (their destructors do not cause any observable effects,
+and may be elided as an optimization).
+
+Rust frames that do contain pending destructors or `catch_unwind` calls are
+called non-POFs.
+
+Note that a non-POF may _become_ a POF, for instance if all `Drop` objects are
+moved out of scope, or if its only `catch_unwind` call is in a code path that
+will not be executed.
+
+[cpp-POD-definition]: https://en.cppreference.com/w/cpp/named_req/PODType
+
 ## Forced unwinding
 [forced-unwinding]: #forced-unwinding
 
@@ -143,16 +169,13 @@ deallocate Rust frames without true unwinding on other platforms.
 This RFC specifies that, regardless of the platform or the ABI string (`"C"` or
 `"C unwind"`), any platform features that may rely on forced unwinding are:
 
-* _undefined behavior_ if they cross frames with destructors or a
-  `catch_unwind` call
-* _defined behavior_ otherwise
+* _undefined behavior_ if they cross non-[POFs][POF-definition]
+* _defined behavior_ when all unwound frames are POFs
 
 As an example, this means that Rust code can (indirectly, via C) invoke
 `longjmp` using the "C" ABI, and that `longjmp` can unwind or otherwise cross
-Rust frames, so long as those frames do not contain any pending destructors or
-make use of `catch_unwind`. If those Rust frames do contain pending
-destructors, then invoking `longjmp` would be undefined behavior (and hence a
-bug).
+Rust [POFs][POF-definition]. If those Rust frames are not POFs, then invoking
+`longjmp` would be undefined behavior (and hence a bug).
 
 [inside-rust-forced]: https://blog.rust-lang.org/inside-rust/2020/02/27/ffi-unwind-design-meeting.html#forced-unwinding
 
@@ -167,8 +190,8 @@ This RFC retains most of that undefined behavior, with two exceptions:
 
 * With the `panic=unwind` runtime, `panic!` will cause an `abort` if it would
   otherwise "escape" from a function defined with `extern "C"`.
-* Forced unwinding is safe with `extern "C"` as long as no frames with
-  destructors (i.e. `Drop` types) are unwound. This is to keep behavior of
+* Forced unwinding is safe with `extern "C"` as long as only
+* [POFs][POF-definition] are unwound. This is to keep behavior of
   `pthread_exit` and `longjmp` consistent across platforms.
 
 ## Interaction with `panic=abort`
@@ -182,7 +205,7 @@ to abort with `panic=abort`, though:
 
 * Forced unwinding: Rust provides no mechanism to catch this type of unwinding.
   This is safe with either the `"C"` ABI or the new `"C unwind"` ABI, as long
-  as none of the unwound Rust frames contain destructors.
+  as only [POFs][POF-definition] are unwound.
 * Unwinding from another language into Rust if the entrypoint to that language
   is declared with `extern "C"` (contrary to the guidelines above): this is
   always undefined behavior.
@@ -206,24 +229,25 @@ Regardless of the panic runtime, ABI, or platform, the interaction of Rust
 frames with C functions that deallocate frames (i.e. functions that may use
 forced unwinding on specific platforms) is specified as follows:
 
-* **When deallocating Rust frames without destructors:** frames are safely
+* **When deallocating Rust [POFs][POF-definition]:** frames are safely
   deallocated; no undefined behavior
-* **When deallocating Rust frames with destructors:** undefined behavior
+* **When deallocating Rust non-POFs:** undefined behavior
 
 No subtype relationship is defined between functions or function pointers using
 different ABIs. This RFC also does not define coercions between `"C"` and
 `"C unwind"`.
 
-As noted in the [summary][summary], if a Rust frame containing `catch_unwind` is unwound by a
-foreign exception, the behavior is undefined for now.
+As noted in the [summary][summary], if a Rust frame containing a pending
+`catch_unwind` call is unwound by a foreign exception, the behavior is
+undefined for now.
 
 # Drawbacks
 [drawbacks]: #drawbacks
 
-Forced unwinding is treated as universally unsafe across frames with
-destructors, but on some platforms it could theoretically be well-defined. As
-noted [above](forced-unwind), however, this would make the UB inconsistent
-across platforms, which is not desirable.
+Forced unwinding is treated as universally unsafe across
+[non-POFs][POF-definition], but on some platforms it could theoretically be
+well-defined. As noted [above](forced-unwind), however, this would make the UB
+inconsistent across platforms, which is not desirable.
 
 This design imposes some burden on existing codebases (mentioned
 [above][motivation]) to change their `extern` annotations to use the new ABI.
@@ -249,12 +273,12 @@ RFC is referred to as "option 2" in that post.
 behavior of a forced unwind across a `"C unwind"` boundary under `panic=abort`.
 Under the current proposal, this type of unwind is permitted, allowing
 `longjmp` and `pthread_exit` to behave "normally" with both the `"C"` and the
-`"C unwind"` ABI across all platforms regardless of panic runtime. If there are
-destructors in the unwound frames, this results in undefined behavior. Under
-"option 1", however, all foreign unwinding, forced or unforced, is caught at
-`"C unwind"` boundaries under `panic=abort`, and the process is aborted. This
-gives `longjmp` and `pthread_exit` surprising behavior on some platforms, but
-avoids that cause of undefined behavior in the current proposal.
+`"C unwind"` ABI across all platforms regardless of panic runtime. If
+[non-POFs][POF-definition] are unwound, this results in undefined behavior.
+Under "option 1", however, all foreign unwinding, forced or unforced, is caught
+at `"C unwind"` boundaries under `panic=abort`, and the process is aborted.
+This gives `longjmp` and `pthread_exit` surprising behavior on some platforms,
+but avoids that cause of undefined behavior in the current proposal.
 
 The other proposal in the blog post, "option 3", is dramatically different. In
 that proposal, foreign exceptions are permitted to cross `extern "C"`
@@ -335,15 +359,13 @@ future work.
 ### Enable error handling with `longjmp`
 
 This constraint is met: `longjmp` is treated the same across all platforms, and
-is safe as long as the deallocated Rust frames do not contain pending `drop` or
-`catch_unwind` calls.
+is safe as long as only [POFs][POF-definition] are deallocated.
 
 ### Do not change the ABI of functions in the `libc` crate
 
 This constraint is met: `libc` functions will continue to use the `"C"` ABI.
 `pthread_exit` will be treated the same across all platforms, and will be safe
-as long as the deallocated Rust frames do not contain pending `drop` or
-`catch_unwind` calls. 
+as long as only [POFs][POF-definition] are deallocated. 
 
 # Prior art
 [prior-art]: #prior-art