Meta tags:
description=Shareable mutable containers.;
keywords=rust, rustlang, rust-lang, cell;

Headings (most frequently used words):

of, module, cell, mutability, immutable, std, when, to, choose, interior, structs, introducing, inside, something, implementation, details, logically, methods, mutating, implementations, clone,

Text of the page (most frequently used words):
the (44), cell (25), refcell (23), value (18), self (18), and (17), mutability (16), that (14), types (13), for (12), #interior (12), use (12), std (11), rust (10), this (10), i32 (9), #method (8), not (8), clone (7), immutable (7), are (7), mutable (6), borrow (6), mutation (6), one (6), borrowed (5), can (5), ptr (5), sized (5), rcbox (5), strong (5), inner (5), must (5), mut (5), vec (5), because (5), implement (5), shared (5), map (5), values (5), references (5), type (4), with (4), reference (4), only (4), common (4), may (4), new (4), insert (4), let (4), dynamic (4), inside (4), aliasing (4), current (4), object (4), refmut (3), memory (3), but (3), experimental (3), which (3), access (3), run (3), phantomdata (3), usize (3), impl (3), struct (3), take (3), mutating (3), there (3), logically (3), implementation (3), you (3), methods (3), threaded (3), shared_map (3), would (3), thread (3), pointer (3), containers (3), multiple (3), mutate (3), something (3), inherited (3), where (3), have (3), when (3), possible (3), replaces (3), returns (3), replaced (3), default (3), unsafecell (2), wrapper (2), mutably (2), from (2), location (2), error (2), returned (2), sync (2), structs (2), nonnull (2), process (2), abort (2), phantom (2), inc_strong (2), rcboxptr (2), get (2), set (2), trait (2), previous (2), change (2), source (2), happens (2), example (2), implementations (2), graph (2), span_tree_cache (2), borrow_mut (2), calc_span_tree (2), details (2), note (2), uses (2), single (2), using (2), need (2), mutex (2), rwlock (2), arc (2), hashmap (2), total (2), out (2), scope (2), then (2), panic (2), smart (2), provide (2), between (2), they (2), all (2), introducing (2), unique (2), about (2), statically (2), even (2), borrows (2), tracked (2), mutated (2), through (2), shareable (2), however (2), rule (2), having (2), also (2), known (2), module (2), web (2), org (2), core, primitive, dynamically, checked, rules, wraps, box, immutably, ref, try_borrow_mut, borrowmuterror, try_borrow, borrowerror, syncunsafecell, written, once, oncecell, initialized, first, lazycell, marker, refcount, checked_add, unwrap_or_else, as_ref, unsafe, simply, special, case, hiding, operations, appear, expected, declared, therefore, any, maintains, its, counts, within, edges, minimum_spanning_tree, get_or_insert_with, expensive, computation, goes, here, option, occasionally, desirable, expose, api, happening, under, hood, operation, caching, forces, perform, employ, was, originally, defined, scenarios, consider, multi, situation, collections, main, sum, println, had, cache, fall, subsequent, cause, major, hazard, marbles, 11826, piccadilly, 11837, kyoto, 92388, africa, create, block, limit, very, put, reintroduce, many, including, cloned, parties, contained, multiply, aliased, without, cells, impossible, data, these, pointers, more, key, language, elements, enables, reason, strongly, preventing, crash, bugs, preferred, last, resort, since, enable, otherwise, disallowed, though, occasions, might, appropriate, used, choose, lifetimes, borrowing, whereby, claim, temporary, exclusive, runtime, unlike, native, entirely, compile, time, attempt, already, results, consumes, additionally, dropping, into_inner, replace, retrieves, copy, come, two, flavors, implements, moving, instead, acquiring, write, lock, before, provides, retrieve, whereas, most, say, contrast, typical, exhibit, exist, permit, controlled, manner, presence, both, allow, doing, way, neither, nor, safe, threads, atomic, enforced, compiler, situations, flexible, enough, sometimes, required, yet, several, safety, based, given, following, expand, description, wayback, machine, http, archive, 20221215013334, https, doc, lang, index, html, timestamps, capture, fail, success, 2023, 2022, 2021, jan, dec, nov, jul, 2014, sep, 2026, 174, captures,

Text of the page (random words):
std cell rust 174 captures 17 jul 2014 08 sep 2026 nov dec jan 15 2021 2022 2023 success fail about this capture timestamps the wayback machine http web archive org web 20221215013334 https doc rust lang org std cell index html module cell structs module std cell 1 0 0 source expand description shareable mutable containers rust memory safety is based on this rule given an object t it is only possible to have one of the following having several immutable references t to the object also known as aliasing having one mutable reference mut t to the object also known as mutability this is enforced by the rust compiler however there are situations where this rule is not flexible enough sometimes it is required to have multiple references to an object and yet mutate it shareable mutable containers exist to permit mutability in a controlled manner even in the presence of aliasing both cell t and refcell t allow doing this in a single threaded way however neither cell t nor refcell t are thread safe they do not implement sync if you need to do aliasing and mutation between multiple threads it is possible to use mutex t rwlock t or atomic types values of the cell t and refcell t types may be mutated through shared references i e the common t type whereas most rust types can only be mutated through unique mut t references we say that cell t and refcell t provide interior mutability in contrast with typical rust types that exhibit inherited mutability cell types come in two flavors cell t and refcell t cell t implements interior mutability by moving values in and out of the cell t to use references instead of values one must use the refcell t type acquiring a write lock before mutating cell t provides methods to retrieve and change the current interior value for types that implement copy the get method retrieves the current interior value for types that implement default the take method replaces the current interior value with default default and returns the replaced value for all types the replace method replaces the current interior value and returns the replaced value and the into_inner method consumes the cell t and returns the interior value additionally the set method replaces the interior value dropping the replaced value refcell t uses rust s lifetimes to implement dynamic borrowing a process whereby one can claim temporary exclusive mutable access to the inner value borrows for refcell t s are tracked at runtime unlike rust s native reference types which are entirely tracked statically at compile time because refcell t borrows are dynamic it is possible to attempt to borrow a value that is already mutably borrowed when this happens it results in thread panic when to choose interior mutability the more common inherited mutability where one must have unique access to mutate a value is one of the key language elements that enables rust to reason strongly about pointer aliasing statically preventing crash bugs because of that inherited mutability is preferred and interior mutability is something of a last resort since cell types enable mutation where it would otherwise be disallowed though there are occasions when interior mutability might be appropriate or even must be used e g introducing mutability inside of something immutable implementation details of logically immutable methods mutating implementations of clone introducing mutability inside of something immutable many shared smart pointer types including rc t and arc t provide containers that can be cloned and shared between multiple parties because the contained values may be multiply aliased they can only be borrowed with not mut without cells it would be impossible to mutate data inside of these smart pointers at all it s very common then to put a refcell t inside shared pointer types to reintroduce mutability use std cell refcell refmut use std collections hashmap use std rc rc fn main let shared_map rc refcell _ rc new refcell new hashmap new create a new block to limit the scope of the dynamic borrow let mut map refmut _ shared_map borrow_mut map insert africa 92388 map insert kyoto 11837 map insert piccadilly 11826 map insert marbles 38 note that if we had not let the previous borrow of the cache fall out of scope then the subsequent borrow would cause a dynamic thread panic this is the major hazard of using refcell let total i32 shared_map borrow values sum println total run note that this example uses rc t and not arc t refcell t s are for single threaded scenarios consider using rwlock t or mutex t if you need shared mutability in a multi threaded situation implementation details of logically immutable methods occasionally it may be desirable not to expose in an api that there is mutation happening under the hood this may be because logically the operation is immutable but e g caching forces the implementation to perform mutation or because you must employ mutation to implement a trait method that was originally defined to take self use std cell refcell struct graph edges vec i32 i32 span_tree_cache refcell option vec i32 i32 impl graph fn minimum_spanning_tree self vec i32 i32 self span_tree_cache borrow_mut get_or_insert_with self calc_span_tree clone fn calc_span_tree self vec i32 i32 expensive computation goes here vec run mutating implementations of clone this is simply a special but common case of the previous hiding mutability for operations that appear to be immutable the clone method is expected to not change the source value and is declared to take self not mut self therefore any mutation that happens in the clone method must use cell types for example rc t maintains its reference counts within a cell t use std cell cell use std ptr nonnull use std process abort use std marker phantomdata struct rc t sized ptr nonnull rcbox t phantom phantomdata rcbox t struct rcbox t sized strong cell usize refcount cell usize value t impl t sized clone for rc t fn clone self rc t self inc_strong rc ptr self ptr phantom phantomdata trait rcboxptr t sized fn inner self rcbox t fn strong self usize self inner strong get fn inc_strong self self inner strong set self strong checked_add 1 unwrap_or_else abort impl t sized rcboxptr t for rc t fn inner self rcbox t unsafe self ptr as_ref run structs lazycell experimental a value which is initialized on the first access oncecell experimental a cell which can be written to only once syncunsafecell experimental unsafecell but sync borrowerror an error returned by refcell try_borrow borrowmuterror an error returned by refcell try_borrow_mut cell a mutable memory location ref wraps a borrowed reference to a value in a refcell box a wrapper type for an immutably borrowed value from a refcell t refcell a mutable memory location with dynamically checked borrow rules refmut a wrapper type for a mutably borrowed value from a refcell t unsafecell the core primitive for interior mutability in rust