std::experi...ope_success(3)

💅 std::experimental::scope_success 💅

okay bestie, so we're talking about std::experimental::scope_success from the C++ Standard Library ✨ it's like, a reeeeally specific little tool and honestly? kinda iconic once you get what it does 🎀

---

✨ NAME ✨

std::experimental::scope_success — yeah that's the whole name, no cap 💖

---

🌸 Synopsis 🌸

so this bad boy lives in the header <experimental/scope> and here's the whole vibe:

template< class EF >                    (library fundamentals TS v3)
class scope_success;

the class template scope_success is a general-purpose scope guard whose entire main character purpose is to call its exit function when a scope is normally exited. periodt 💅

now listen up: scope_success is not CopyConstructible, not CopyAssignable, and not MoveAssignable — like, it does NOT do copies of itself bestie 🙅‍♀️ but! it may be MoveConstructible if EF meets some requirements, which is what lets you wrap a scope_success into another object. slay 🦋

a scope_success can be either:

• active — meaning it calls its exit function on destruction 🔥
• inactive — meaning it literally does nothing on destruction 💀

a scope_success is active after it's constructed from an exit function. simple as that ✨

you can make it inactive by calling release() on it, either manually or automatically (the move constructor does it for you, cute 🎀). you can ALSO get an inactive one by initializing with another inactive scope_success. but here's the tea: once a scope_success is inactive, it cannot become active again. no take-backs, no revivals, it's over 😭

under the hood a scope_success effectively holds an EF and a <yellow>bool</yellow> flag saying if it's active, along with a counter of uncaught exceptions — that counter is how it detects whether the destructor is being called during stack unwinding. iykyk 🧚

---

🦋 Template parameters 🦋

• EF — type of stored exit function 💜

---

🎀 Type requirements 🎀

• EF shall be either:
  • a Destructible FunctionObject type,
  • an lvalue reference to FunctionObject,
  • an lvalue reference to function.
• Calling an lvalue of std::remove_reference_t<EF> with no argument shall be well-formed. no notes, just facts 💅

---

🔥 Member functions 🔥

• constructor — constructs a new scope_success (public member function) 🌈
• destructor — calls the exit function when the scope is exited normally if the scope_success is active, then destroys the scope_success (public member function) 💀
• operator= — scope_success is not assignable [deleted] (public member function) 🙈

---

⭐ Modifiers ⭐

• release — makes the scope_success inactive (public member function) 🫶

Deduction guides

(yes bestie, there are deduction guides in the mix ✨)

---

💀 Notes 💀

okay these are the warnings, pay attention fr fr 👑

• Constructing a scope_success of dynamic storage duration might lead to unexpected behavior 😬
• Constructing a scope_success from another scope_success created in a different thread might also lead to unexpected behavior, since the count of uncaught exceptions obtained in different threads may be compared during the destruction. threading said "not today" 😭
• If the EF stored in a scope_success object refers to a local variable of the function where it's defined — like, say, a lambda capturing the variable by reference — and that variable is used as a return operand in that function, then that variable might have already been returned when the scope_success's destructor executes and calls the exit function. which can lead to surprising behavior 💀 consider yourself warned bestie

---

🍓 Example 🍓

This section is incomplete Reason: no example

(yeah, they really left us hanging on this one 😭 no example for us, tragic)

---

🌸 See also 🌸

• scope_exit — wraps a function object and invokes it on exiting the scope (class template) 🦋
• scope_fail — wraps a function object and invokes it on exiting the scope through an exception (class template) 🔥
• default_delete — default deleter for unique_ptr (C++11) (class template) 💜

Category:

• Todo no example 🙈

---

okay that's the whole page bestie, you're officially a scope_success expert now, go forth and guard those scopes 👑💖

source: cppreference.com, dated 2024.06.10 — mwah, love u, bye 🫶✨