UNW_SET..._POLICY(3libunwind)

💖 UNW_SET..._POLICY(3libunwind) 💖

okay bestie, you found the 3libunwind Programming Library page for UNW_SET..._POLICY and honestly? you're about to be so good at caching. no cap. let's get into it 🦋

---

✨ NAME ✨

unw_set_caching_policy — set unwind caching policy

like, it sets the caching policy. that's the whole gig. and it's iconic for it 💅

---

🌸 SYNOPSIS 🌸

#include <libunwind.h>

int unw_set_caching_policy(unw_addr_space_t as, unw_caching_policy_t
policy);

look at that signature. two args. as is your address space, policy is your vibe. and it hands you back an int. chef's kiss 🎀

---

💫 DESCRIPTION 💫

so the unw_set_caching_policy() routine sets the caching policy of address space as to whatever policy you passed in. that's it, that's the function.

and policy can be one of three possible values, so let's meet the whole squad:

• UNW_CACHE_NONE — turns caching off completely. and not just "off going forward" — this also implicitly flushes the contents of all caches as if unw_flush_cache() had been called. so it's a full reset, no leftovers, so clean ✨
• UNW_CACHE_GLOBAL — enables caching using a global cache that is shared by all threads. but lowkey, if global caching is unavailable or unsupported, libunwind may fall back on using a per-thread cache, as if UNW_CACHE_PER_THREAD had been specified. so it's giving "I'll try my best, but I have a backup plan" 🫶
• UNW_CACHE_PER_THREAD — enables caching using thread-local caches. and same energy in reverse: if a thread-local caching are unavailable or unsupported, libunwind may fall back on using a global cache, as if UNW_CACHE_GLOBAL had been specified. mutual fallback besties fr fr 🔥

⚠️ important, bestie, listen up: if caching is enabled, an application must be prepared to make appropriate calls to unw_flush_cache() whenever the target changes in a way that could affect the validity of cached information. for example, after unloading (removing) a shared library, unw_flush_cache() would have to be called (at least) for the address-range that was covered by the shared library. this is not optional, this is the whole deal. stale cache = chaos 💀

and the defaults? here's the tea:

• for address spaces created via unw_create_addr_space(3libunwind), caching is turned off by default. 🚫
• for the local address space unw_local_addr_space, caching is turned on by default. ✅

---

🎀 RETURN VALUE 🎀

on successful completion, unw_set_caching_policy() returns 0. slay. otherwise, the negative value of one of the error-codes below is returned. so if you see a negative number, that's a "no" with extra steps 😭

---

🧚 THREAD AND SIGNAL SAFETY 🧚

unw_set_caching_policy() is thread-safe 👑 but not safe to use from a signal handler. so like, call it from your threads all you want, just don't be calling it from inside a signal handler. that's the boundary. respect it 💜

---

🌈 ERRORS 🌈

• UNW_ENOMEM — the desired caching policy could not be established because the application is out of memory. out of memory! the audacity 😤

---

⭐ SEE ALSO ⭐

• libunwind(3libunwind)
• unw_create_addr_space(3libunwind)
• unw_set_cache_size(3libunwind)
• unw_flush_cache(3libunwind)

go read these next, iykyk 📚

---

💅 AUTHOR 💅

David Mosberger-Tang Email: dmosberger@gmail.com WWW: http://www.nongnu.org/libunwind/

---

and that's the page!! this one's from the Programming Library, dated 29 August 2023, and it's filed under UNW_SET..._POLICY(3libunwind). you understood the assignment, bestie 🫶✨