persistent_term(3)

💖 persistent_term(3) — Erlang Module Definition 💖

okay bestie, welcome to persistent_term, the Erlang module that's literally the "read it a million times, write it basically never" queen 👑. It lives in the erts manual (hi, it's giving core-Erlang energy), and she's so iconic for lookups and so dramatic about writes. Let's get into it 🫶

---

✨ NAME ✨

persistent_term — persistent terms, bestie. that's it, that's the name 💅

---

🌸 DESCRIPTION 🌸

okay so first thing: this module is similar to ets in that it gives you a storage for Erlang terms that can be accessed in constant time. BUT 🔥 the difference is that persistent_term has been highly optimized for reading terms at the expense of writing and updating terms. reading? slay. writing? girl, brace yourself.

when a persistent term is updated or deleted, a global garbage collection pass is run to scan all processes for the deleted term, and to copy it into each process that still uses it. so yeah. that's a whole thing. therefore, persistent_term is suitable for storing Erlang terms that are frequently accessed but never or infrequently updated. iykyk 💜

WARNING: Persistent terms is an advanced feature and is not a general replacement for ETS tables. Before using persistent terms, make sure to fully understand the consequence to system performance when updating or deleting persistent terms. no cap, read that twice bestie 😭

term lookup (using get/1) is done in constant time and without taking any locks, and the term is not copied to the heap (as is the case with terms stored in ETS tables). it's giving free real estate ✨

storing or updating a term (using put/2) is proportional to the number of already created persistent terms because the hash table holding the keys will be copied. in addition, the term itself will be copied. yeah. both. 🙈

when a (complex) term is deleted (using erase/1) or replaced by another (using put/2), a global garbage collection is initiated. it works like this:

• All processes in the system will be scheduled to run a scan of their heaps for the term that has been deleted. While such scan is relatively light-weight, if there are many processes, the system can become less responsive until all processes have scanned their heaps. not the vibe check anyone wants 💀
• If the deleted term (or any part of it) is still used by a process, that process will do a major (fullsweep) garbage collection and copy the term into the process. However, at most two processes at a time will be scheduled to do that kind of garbage collection. two. at a time. iconic restraint ✋

deletion of atoms and other terms that fit in one machine word is specially optimized to avoid doing a global GC. it's still not recommended to update persistent terms with such values too frequently because the hash table holding the keys is copied every time a persistent term is updated. so like, it's better, not free 🍓

some examples that are suitable uses for persistent terms are:

• Storing of configuration data that must be easily accessible by all processes. 💖
• Storing of references for NIF resources. 🧚
• Storing of references for efficient counters. ⭐
• Storing an atom to indicate a logging level or whether debugging is turned on. 🌈

---

🎀 Storing Huge Persistent Terms 🎀

the current implementation of persistent terms uses the literal allocator also used for literals (constant terms) in BEAM code. by default, 1 GB of virtual address space is reserved for literals in BEAM code and persistent terms. the amount of virtual address space reserved for literals can be changed by using the +MIscs option when starting the emulator. fancy ✨

here is an example how the reserved virtual address space for literals can be raised to 2 GB (2048 MB):

erl +MIscs 2048

---

🦋 Best Practices for Using Persistent Terms 🦋

• It is recommended to use keys like ?MODULE or {?MODULE,SubKey} to avoid name collisions. protect your namespace bestie 🫶
• Prefer creating a few large persistent terms to creating many small persistent terms. The execution time for storing a persistent term is proportional to the number of already existing terms. big moods, small counts 💅
• Updating a persistent term with the same value as it already has is specially optimized to do nothing quickly; thus, there is no need compare the old and new values and avoid calling put/2 if the values are equal. so just call it, she'll handle it 🔥
• When atoms or other terms that fit in one machine word are deleted, no global GC is needed. Therefore, persistent terms that have atoms as their values can be updated more frequently, but note that updating such persistent terms is still much more expensive than reading them. reading stays undefeated 👑
• Updating or deleting a persistent term will trigger a global GC if the term does not fit in one machine word. Processes will be scheduled as usual, but all processes will be made runnable at once, which will make the system less responsive until all processes have run and scanned their heaps for the deleted terms. One way to minimize the effects on responsiveness could be to minimize the number of processes on the node before updating or deleting a persistent term. It would also be wise to avoid updating terms when the system is at peak load. timing is everything fr fr 😭
• Avoid storing a retrieved persistent term in a process if that persistent term could be deleted or updated in the future. If a process holds a reference to a persistent term when the term is deleted, the process will be garbage collected and the term copied to the process. don't cling, babe 🙈
• Avoid updating or deleting more than one persistent term at a time. Each deleted term will trigger its own global GC. That means that deleting N terms will make the system less responsive N times longer than deleting a single persistent term. Therefore, terms that are to be updated at the same time should be collected into a larger term, for example, a map or a tuple. bundle them, don't spam them 🎀

---

🌈 Example 🌈

the following example shows how lock contention for ETS tables can be minimized by having one ETS table for each scheduler. the table identifiers for the ETS tables are stored as a single persistent term:

%% There is one ETS table for each scheduler.
Sid = erlang:system_info(scheduler_id),
Tid = element(Sid, persistent_term:get(?MODULE)),
ets:update_counter(Tid, Key, 1).

---

⭐ DATA TYPES ⭐

• key() :: term(). Any Erlang term. like, literally any. anything. go wild 💜
• value() :: term(). Any Erlang term. yes, also any. the range is unhinged and we love that for her 🌸

---

💅 FUNCTIONS 💅

• erase(Key) -> Result when Key :: key(), Result :: boolean(). — Erase the name for the persistent term with key Key.

The return value will be true if there was a persistent term with the key Key, and false if there was no persistent term associated with the key.

If there existed a previous persistent term associated with key Key, a global GC has been initiated when erase/1 returns. See Description. yeah. that global GC. bestie you were warned 😭

• get() -> List when List :: [{key(), value()}]. — Retrieve the keys and values for all persistent terms.

The keys will be copied to the heap for the process calling get/0, but the values will not. half copied, half iconic ✨

• get(Key) -> Value when Key :: key(), Value :: value(). — Retrieve the value for the persistent term associated with the key Key.

The lookup will be made in constant time and the value will not be copied to the heap of the calling process.

This function fails with a badarg exception if no term has been stored with the key Key. not found = badarg, no gentle default, periodt 💀

If the calling process holds on to the value of the persistent term and the persistent term is deleted in the future, the term will be copied to the process.

• get(Key, Default) -> Value when Key :: key(), Default :: value(), Value :: value(). — Retrieve the value for the persistent term associated with the key Key.

The lookup will be made in constant time and the value will not be copied to the heap of the calling process.

This function returns Default if no term has been stored with the key Key. look at her being polite 🫶

If the calling process holds on to the value of the persistent term and the persistent term is deleted in the future, the term will be copied to the process.

• info() -> Info when Info :: #{count := Count, memory := Memory}, Count :: non_neg_integer(), Memory :: non_neg_integer(). — Return information about persistent terms in a map.

The map has the following keys:

• count — The number of persistent terms. 🔢
• memory — The total amount of memory (measured in bytes) used by all persistent terms. 🧮

• put(Key, Value) -> ok when Key :: key(), Value :: value(). — Store the value Value as a persistent term and associate it with the key Key.

If the value Value is equal to the value previously stored for the key, put/2 will do nothing and return quickly. the no-op glow-up 💅

If there existed a previous persistent term associated with key Key, a global GC has been initiated when put/2 returns. See Description.

• put_new(Key, Value) -> ok when Key :: key(), Value :: value(). — Store the value Value as a persistent term and associate it with the key Key if the key Key doesn't already exist.

If the value Value is equal to the value previously stored for the key, put_new/2 will do nothing and return quickly.

If there existed a previous persistent term associated with key Key, the function fails with a badarg exception. she said no duplicates, babe 🌸

---

aaaand that's the whole page, bestie 🎀 no skips, no summarising, every flag and every warning accounted for 💖

this whole thing came to you from Ericsson AB, shipped as part of erts version 17.0.6, filed under persistent_term(3). go forth and cache responsibly, and remember: read often, write rarely, and never at peak load 🫶✨👑