ArcShift

https://docs.rs/arcshift/0.4.4
Admin
ArcShift is a lock-free Rust smart pointer data type similar to std::sync::Arc that allows updating...
Tokens:23,737
Snippets:318
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### ArcShift Usage Example

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShift.html?search=

Basic initialization and retrieval of a value stored in an ArcShift instance.

```rust
let mut instance = ArcShift::new("test");
println!("Value: {:?}", instance.get());
```

--------------------------------

### Reload the ArcShiftCell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Triggers a reload to drop heap blocks no longer needed. This method is a no-op if called during a get closure.

```rust
pub fn reload(&self) {
    if self.recursion.get() == 0 {
        // SAFETY:
        // For 'reload' to be safe, we must be sure that no other execution has a reference
        // to 'self.item', since the value it points to might be dropped.
        // This guarantee is fulfilled, because there is no way to get such a reference
        // other than receiving it in the callback given to 'get'. And for as long as the
        // callback is executing, 'recursion' will be != 0.
        unsafe { &mut *self.inner.get() }.reload()
    }
}
```

--------------------------------

### Using ArcShift for Thread-Safe Data Sharing

Source: https://docs.rs/arcshift/0.4.4/arcshift/index.html?search=

Demonstrates initializing an ArcShift instance, cloning it for use across threads, and performing read and update operations.

```rust
use std::thread;


let mut arc = ArcShift::new("Hello".to_string());
let mut arc2 = arc.clone();


let j1 = thread::spawn(move||{
    println!("Value in thread 1: '{}'", arc.get()); //Prints 'Hello'
    arc.update("New value".to_string());
    println!("Updated value in thread 1: '{}'", arc.get()); //Prints 'New value'
});

let j2 = thread::spawn(move||{
    // Prints either 'Hello' or 'New value', depending on scheduling:
    println!("Value in thread 2: '{}'", arc2.get());
});

j1.join().unwrap();
j2.join().unwrap();
```

--------------------------------

### Access the inner value with get

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Provides reentrant access to the inner value via a closure. Only the outermost invocation triggers a reload.

```rust
#[inline]
pub fn get<R>(&self, f: impl FnOnce(&T) -> R) -> R {
    self.recursion.set(self.recursion.get() + 1);
    let val = if self.recursion.get() == 1 {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        unsafe { &mut *self.inner.get() }.get()
    } else {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        unsafe { &*self.inner.get() }.shared_non_reloading_get()
    };
    let t = f(val);
    self.recursion.set(self.recursion.get() - 1);
    t
}
```

--------------------------------

### Create New ArcShiftCell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Constructor methods for initializing an ArcShiftCell.

```rust
impl<T: 'static> ArcShiftCell<T> {
    /// Create a new ArcShiftCell with the given value.
    pub fn new(value: T) -> ArcShiftCell<T> {
        ArcShiftCell::from_arcshift(ArcShift::new(value))
    }
}
impl<T: 'static + ?Sized> ArcShiftCell<T> {
    /// Creates an ArcShiftCell from an ArcShift-instance.

```

--------------------------------

### Implementing ArcShift for Hot-Reloading Assets

Source: https://docs.rs/arcshift/0.4.4/arcshift/index.html?search=

Demonstrates using ArcShift to manage a collection of character models that can be updated dynamically from a background thread while being accessed by the main game loop.

```rust
struct CharacterModel {
    /* 3D model, textures, etc*/
}

struct World {
    models: Vec<ArcShift<CharacterModel>>
}

/// Loads models. Regularly scans filesystem,
/// updates models when their files change on disk.
fn load_models() -> Vec<ArcShift<CharacterModel>> {
    let models: Vec<ArcShift<CharacterModel>> = vec![];

    /* Somehow load models */

    let mut models_for_reloader = models.clone();
    std::thread::spawn(move||{
        loop {
            /* detect file system changes*/
            let changed_model = 0usize;

            models_for_reloader[changed_model].update(CharacterModel{/* newly loaded*/});
        }

    });

    models
}

fn run_game() {
    let mut world = World {
        models: load_models()
    };
    loop {
        run_game_logic(&mut world);
    }
}

fn run_game_logic(world: &mut World) {
    /*
        Do game logic, possibly in multiple threads, accessing different parts of World,
        possibly cloning 'ArcShift' instances for use by other threads
    */

    for model in world.models.iter_mut() {
        // Accessing ArcShift using 'get' ensures
        // old versions do not linger in RAM.
        let model_ref : &CharacterModel = model.get();
        // Do stuff with 'model_ref'
    }
}
```

--------------------------------

### ArcShiftCell Implementation Methods

Source: https://docs.rs/arcshift/0.4.4/arcshift/cell/struct.ArcShiftCell.html?search=

Methods for creating, borrowing, and managing the state of an ArcShiftCell.

```rust
pub fn new(value: T) -> ArcShiftCell<T>
```

```rust
pub fn from_arcshift(input: ArcShift<T>) -> ArcShiftCell<T>
```

```rust
pub fn borrow(&self) -> ArcShiftCellHandle<'_, T>
```

```rust
pub fn get<R>(&self, f: impl FnOnce(&T) -> R) -> R
```

```rust
pub fn assign(&self, other: &ArcShift<T>) -> Result<(), RecursionDetected>
```

```rust
pub fn reload(&self)
```

```rust
pub fn make_arcshift(&self) -> ArcShift<T>
```

--------------------------------

### pub fn upgrade(&self) -> Option<ArcShift<T>>

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShiftWeak.html?search=std%3A%3Avec

Attempts to upgrade the ArcShiftWeak pointer to a full ArcShift instance. Returns Some(ArcShift<T>) if the value still exists, or None if the original ArcShift has been deallocated.

```APIDOC
## pub fn upgrade(&self) -> Option<ArcShift<T>>

### Description
Attempts to upgrade this ArcShiftWeak instance to a full ArcShift. This is required to access the stored value. If the original ArcShift instance has been deallocated, this method returns None.

### Returns
- **Option<ArcShift<T>>** - An Option containing the upgraded ArcShift if successful, otherwise None.
```

--------------------------------

### Usage of ArcShiftWeak

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShiftWeak.html?search=u32+-%3E+bool

Demonstrates creating a weak reference from an ArcShift instance and upgrading it back to access the value.

```rust
let original_instance = ArcShift::new("test");
let light_instance = ArcShift::downgrade(&original_instance);
let mut instance = light_instance.upgrade().unwrap();
println!("Value: {:?}", instance.get());
```

--------------------------------

### Implement DropHandler for deferred panic management

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/deferred_panics_helper/std_drop_handler.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines the DropHandler structure and its implementation of IDropHandler to safely execute drop logic while catching potential panics.

```rust
use crate::deferred_panics_helper::IDropHandler;
use crate::{debug_println, IMetadata, ItemHolder};
use core::any::Any;
use core::marker::PhantomData;
use core::mem::ManuallyDrop;

/// A drop handler that will persist the most recent panic, allowing it
/// to be unwinded later
pub(crate) struct DropHandler<T: ?Sized> {
    panic: Option<alloc::boxed::Box<dyn Any + Send + 'static>>,
    phantom: PhantomData<*mut T>,
}

impl<T: ?Sized> Default for DropHandler<T> {
    fn default() -> Self {
        Self {
            panic: None,
            phantom: Default::default(),
        }
    }
}

impl<T: ?Sized, M: IMetadata> IDropHandler<T, M> for DropHandler<T> {
    fn do_drop(&mut self, item_ptr: *mut ItemHolder<T, M>) {
        self.run(|| {
            // SAFETY: item_ptr must be valid, guaranteed by caller.
            let payload = unsafe { &(*item_ptr).payload };
            debug_println!("payload ref created (std drop)");

            // SAFETY: item_ptr is now uniquely owned. We can drop it.
            unsafe { ManuallyDrop::drop(&mut *payload.get()) };
            debug_println!("payload dropped");
        })
    }

    fn report_sole_user(&mut self) {}
}

impl<T: ?Sized> DropHandler<T> {
    pub(crate) fn do_drop_value(&mut self, value: T)
    where
        T: Sized,
    {
        self.run(move || {
            let _ = value;
        });
    }
    pub(crate) fn run(&mut self, job: impl FnOnce()) {
        // We do use AssertUnwindSafe here.
        // Most of the time, this is perfectly fine, since this crate doesn't
        // care about the internals of the payload type (T), so any inconsistency
        // left there is fine to this crate. For the user, they won't typically
        // observe any inconsistency either, since we resume_unwind (re-throw) this panic
        // before returning to the user.
        //
        // There is one exception to this. For example, if multiple objects are dropped in the same
        // ArcShift-invocation, and the first drop panics, and the second object has a
        // reference to some third object that the first drop partially updated and left in
        // an inconsistent state.
        //
        // This is deemed acceptable. Alternatives would be :
        //
        // * Require that all payload objects implement UnwindSafe. Clearly annoying.
        // * Don't run subsequent drop-methods if the first panicked. Since leaking is safe,
        //   this is perhaps technically more idiomatic than the chosen solution. However,
        //   Drop-impls should rarely need to update foreign objects, and also, drop-methods
        //   really shouldn't panic at all.

        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(job)) {
            Ok(()) => {}
            Err(err) => {
                self.panic.get_or_insert(err);
            }
        }
    }
    pub(crate) fn resume_any_panics(self) {
        if let Some(panic) = self.panic {
            std::panic::resume_unwind(panic);
        }
    }
}
```

--------------------------------

### Create an ArcShiftCell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Initializes an ArcShiftCell from an existing ArcShift instance without cloning the underlying payload.

```rust
pub fn from_arcshift(input: ArcShift<T>) -> ArcShiftCell<T> {
    ArcShiftCell {
        inner: UnsafeCell::new(input),
        recursion: Cell::new(0),
    }
}
```

--------------------------------

### ArcShiftCell::new

Source: https://docs.rs/arcshift/0.4.4/arcshift/cell/struct.ArcShiftCell.html?search=

Creates a new ArcShiftCell instance with the provided value.

```APIDOC
### pub fn new(value: T) -> ArcShiftCell<T>

Creates a new ArcShiftCell with the given value.
```

--------------------------------

### ArcShiftCell Method Implementations

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html?search=u32+-%3E+bool

Core methods for managing ArcShiftCell state, including reentrant access and safe updates.

```rust
pub fn from_arcshift(input: ArcShift<T>) -> ArcShiftCell<T> {
    ArcShiftCell {
        inner: UnsafeCell::new(input),
        recursion: Cell::new(0),
    }
}
```

```rust
#[inline]
pub fn borrow(&self) -> ArcShiftCellHandle<'_, T> {
    self.recursion.set(self.recursion.get() + 1);
    ArcShiftCellHandle {
        cell: self,
        _marker: PhantomData,
    }
}
```

```rust
#[inline]
pub fn get<R>(&self, f: impl FnOnce(&T) -> R) -> R {
    self.recursion.set(self.recursion.get() + 1);
    let val = if self.recursion.get() == 1 {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        unsafe { &mut *self.inner.get() }.get()
    } else {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        unsafe { &*self.inner.get() }.shared_non_reloading_get()
    };
    let t = f(val);
    self.recursion.set(self.recursion.get() - 1);
    t
}
```

```rust
pub fn assign(&self, other: &ArcShift<T>) -> Result<(), RecursionDetected> {
    if self.recursion.get() == 0 {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        *unsafe { &mut *self.inner.get() } = other.clone();
        Ok(())
    } else {
        Err(RecursionDetected)
    }
}
```

```rust
pub fn reload(&self) {
    if self.recursion.get() == 0 {
        // SAFETY:
        // For 'reload' to be safe, we must be sure that no other execution has a reference
        // to 'self.item', since the value it points to might be dropped.
        // This guarantee is fulfilled, because there is no way to get such a reference
        // other than receiving it in the callback given to 'get'. And for as long as the
        // callback is executing, 'recursion' will be != 0.
        unsafe { &mut *self.inner.get() }.reload()
    }
}
```

```rust
pub fn make_arcshift(&self) -> ArcShift<T> {
    // SAFETY:
    // ArcShiftCell is not Sync, and 'make_arcshift' does not recursively call into user
    // code, so we know no other operation can be ongoing.
    unsafe { &mut *self.inner.get() }.clone()
}
```

--------------------------------

### ArcShift<T> Methods

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShift.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Core methods for creating, updating, and accessing values within an ArcShift instance.

```APIDOC
## ArcShift<T> Methods

### new(val: T) -> ArcShift<T>
Creates a new ArcShift instance with the given value.

### try_into_inner(self) -> Option<T>
Drops this ArcShift instance. If this was the last instance of the entire chain, the payload value is returned.

### update(&mut self, val: T)
Update the value of this ArcShift instance (and all derived from it) to the given value.

### rcu(&mut self, update: impl FnMut(&T) -> T) -> &T
Atomically update the value using a closure. Returns a reference to the newly-set value.

### rcu_maybe(&mut self, update: impl FnMut(&T) -> Option<T>) -> bool
Atomically update the value. If the closure returns None, the update is canceled and the method returns false.

### from_box(input: Box<T>) -> ArcShift<T>
Creates an ArcShift instance from a Box, avoiding stack copies.

### try_get_mut(&mut self) -> Option<&mut T>
Returns a mutable reference to the inner value if no other instances exist.

### update_box(&mut self, new_payload: Box<T>)
Updates the value using a Box, required for unsized types.

### get(&mut self) -> &T
Advances this instance to the most recent value and returns a reference.

### shared_get(&self) -> SharedGetGuard<'_, T>
Gets the current value. Note: may incur a performance penalty if the instance is stale.

### shared_non_reloading_get(&self) -> &T
Gets the current value without reloading. May return a stale value.

### downgrade(this: &ArcShift<T>) -> ArcShiftWeak<T>
Creates a weak reference to the ArcShift instance.

### reload(&mut self)
Advances this instance to the most recent value, freeing superseded values.
```

--------------------------------

### ArcShiftCell Trait Implementations and Constructors

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Provides Send, Clone, and initialization methods for ArcShiftCell.

```rust
unsafe impl<T: 'static> Send for ArcShiftCell<T> where T: Send + Sync {}

impl<T: 'static + ?Sized> Clone for ArcShiftCell<T> {
    fn clone(&self) -> Self {
        // SAFETY:
        // Accessing the inner value is safe, since we know no other thread
        // can be interacting with it. And even if we're in a recursive call to
        // 'get', we're not mutating the value and cloning it is thus perfectly safe.
        let clone = unsafe { &mut *self.inner.get() }.clone();
        ArcShiftCell {
            inner: UnsafeCell::new(clone),
            recursion: Cell::new(0),
        }
    }
}

impl<T: 'static> ArcShiftCell<T> {
    /// Create a new ArcShiftCell with the given value.
    pub fn new(value: T) -> ArcShiftCell<T> {
        ArcShiftCell::from_arcshift(ArcShift::new(value))
    }
}
```

--------------------------------

### DropHandler Implementation

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/deferred_panics_helper/std_drop_handler.rs.html

The DropHandler struct and its associated methods for capturing and resuming panics during drop operations.

```rust
1use crate::deferred_panics_helper::IDropHandler;
2use crate::{debug_println, IMetadata, ItemHolder};
3use core::any::Any;
4use core::marker::PhantomData;
5use core::mem::ManuallyDrop;
6
7/// A drop handler that will persist the most recent panic, allowing it
8/// to be unwinded later
9pub(crate) struct DropHandler<T: ?Sized> {
10    panic: Option<alloc::boxed::Box<dyn Any + Send + 'static>>,
11    phantom: PhantomData<*mut T>,
12}
13
14impl<T: ?Sized> Default for DropHandler<T> {
15    fn default() -> Self {
16        Self {
17            panic: None,
18            phantom: Default::default(),
19        }
20    }
21}
22
23impl<T: ?Sized, M: IMetadata> IDropHandler<T, M> for DropHandler<T> {
24    fn do_drop(&mut self, item_ptr: *mut ItemHolder<T, M>) {
25        self.run(|| {
26            // SAFETY: item_ptr must be valid, guaranteed by caller.
27            let payload = unsafe { &(*item_ptr).payload };
28            debug_println!("payload ref created (std drop)");
29
30            // SAFETY: item_ptr is now uniquely owned. We can drop it.
31            unsafe { ManuallyDrop::drop(&mut *payload.get()) };
32            debug_println!("payload dropped");
33        })
34    }
35
36    fn report_sole_user(&mut self) {}
37}
38
39impl<T: ?Sized> DropHandler<T> {
40    pub(crate) fn do_drop_value(&mut self, value: T)
41    where
42        T: Sized,
43    {
44        self.run(move || {
45            let _ = value;
46        });
47    }
48    pub(crate) fn run(&mut self, job: impl FnOnce()) {
49        // We do use AssertUnwindSafe here.
50        // Most of the time, this is perfectly fine, since this crate doesn't
51        // care about the internals of the payload type (T), so any inconsistency
52        // left there is fine to this crate. For the user, they won't typically
53        // observe any inconsistency either, since we resume_unwind (re-throw) this panic
54        // before returning to the user.
55        //
56        // There is one exception to this. For example, if multiple objects are dropped in the same
57        // ArcShift-invocation, and the first drop panics, and the second object has a
58        // reference to some third object that the first drop partially updated and left in
59        // an inconsistent state.
60        //
61        // This is deemed acceptable. Alternatives would be :
62        //
63        // * Require that all payload objects implement UnwindSafe. Clearly annoying.
64        // * Don't run subsequent drop-methods if the first panicked. Since leaking is safe,
65        //   this is perhaps technically more idiomatic than the chosen solution. However,
66        //   Drop-impls should rarely need to update foreign objects, and also, drop-methods
67        //   really shouldn't panic at all.
68
69        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(job)) {
70            Ok(()) => {}
71            Err(err) => {
72                self.panic.get_or_insert(err);
73            }
74        }
75    }
76    pub(crate) fn resume_any_panics(self) {
77        if let Some(panic) = self.panic {
78            std::panic::resume_unwind(panic);
79        }
80    }
81}
```

--------------------------------

### Implement Debug for ArcShiftCell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Formats the ArcShiftCell for debugging purposes.

```rust
impl<T: ?Sized + 'static> Debug for ArcShiftCell<T>
where
    T: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        write!(f, "ArcShiftCell({:?})", &*self.borrow())
    }
}
```

--------------------------------

### Create an ArcShift instance from cell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Creates a new ArcShift instance pointing to the same value as the cell.

```rust
pub fn make_arcshift(&self) -> ArcShift<T> {
    // SAFETY:
    // ArcShiftCell is not Sync, and 'make_arcshift' does not recursively call into user
    // code, so we know no other operation can be ongoing.
    unsafe { &mut *self.inner.get() }.clone()
}
```

--------------------------------

### ArcShiftCell Trait Implementations and Helpers

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html?search=u32+-%3E+bool

Implementations for Send, Clone, and error handling for ArcShiftCell.

```rust
/// ArcShiftCell cannot be Sync, but there's nothing stopping it from being Send.
///
/// Note that ArcShiftCell *cannot* be Sync, because then multiple threads
/// could call 'get' simultaneously, corrupting the (non-atomic) refcount.
// SAFETY:
// As long as the contents of the cell are not !Send, it is safe to
// send the cell. The object must be uniquely owned to be sent, and
// this is only possible if we're not in a recursive call to
// 'get'. And in this case, the properties of ArcShiftCell are the same
// as ArcShift, and ArcShift is Send (if T is Send + Sync).
//
unsafe impl<T: 'static> Send for ArcShiftCell<T> where T: Send + Sync {}

impl<T: 'static + ?Sized> Clone for ArcShiftCell<T> {
    fn clone(&self) -> Self {
        // SAFETY:
        // Accessing the inner value is safe, since we know no other thread
        // can be interacting with it. And even if we're in a recursive call to
        // 'get', we're not mutating the value and cloning it is thus perfectly safe.
        let clone = unsafe { &mut *self.inner.get() }.clone();
        ArcShiftCell {
            inner: UnsafeCell::new(clone),
            recursion: Cell::new(0),
        }
    }
}

/// Error type representing the case that an operation was attempted from within
/// a 'get'-method closure.
pub struct RecursionDetected;

impl Debug for RecursionDetected {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        write!(f, "RecursionDetected")
    }
}

impl Display for RecursionDetected {
    fn fmt(&self, f: &mut Formatter<'_>) -> core::fmt::Result {
        write!(f, "RecursionDetected")
    }
}

impl<T: 'static> ArcShiftCell<T> {
    /// Create a new ArcShiftCell with the given value.
    pub fn new(value: T) -> ArcShiftCell<T> {
        ArcShiftCell::from_arcshift(ArcShift::new(value))
    }
}
impl<T: 'static + ?Sized> ArcShiftCell<T> {
    /// Creates an ArcShiftCell from an ArcShift-instance.

```

--------------------------------

### ArcShiftCell::make_arcshift

Source: https://docs.rs/arcshift/0.4.4/arcshift/cell/struct.ArcShiftCell.html?search=

Creates an ArcShift instance pointing to the same value as the cell.

```APIDOC
### pub fn make_arcshift(&self) -> ArcShift<T>

Create an ArcShift-instance pointing to the same value as this cell.
```

--------------------------------

### ArcShift Struct Definition

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShift.html?search=

The definition of the ArcShift smart pointer structure.

```rust
pub struct ArcShift<T: ?Sized> { /* private fields */ }
```

--------------------------------

### Implement Send and Clone for ArcShiftCell

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines thread-safety and cloning behavior for the ArcShiftCell container.

```rust
unsafe impl<T: 'static> Send for ArcShiftCell<T> where T: Send + Sync {}

impl<T: 'static + ?Sized> Clone for ArcShiftCell<T> {
    fn clone(&self) -> Self {
        // SAFETY:
        // Accessing the inner value is safe, since we know no other thread
        // can be interacting with it. And even if we're in a recursive call to
        // 'get', we're not mutating the value and cloning it is thus perfectly safe.
        let clone = unsafe { &mut *self.inner.get() }.clone();
        ArcShiftCell {
            inner: UnsafeCell::new(clone),
            recursion: Cell::new(0),
        }
    }
}
```

--------------------------------

### ArcShiftCell::borrow

Source: https://docs.rs/arcshift/0.4.4/arcshift/cell/struct.ArcShiftCell.html?search=

Obtains a handle to the underlying value.

```APIDOC
### pub fn borrow(&self) -> ArcShiftCellHandle<'_, T>

Get a handle to the pointed-to T. Make sure not to leak this handle as it may cause resource leaks.
```

--------------------------------

### Define SharedGetGuard Enum

Source: https://docs.rs/arcshift/0.4.4/arcshift/enum.SharedGetGuard.html

The structure definition for the SharedGetGuard enum.

```rust
pub enum SharedGetGuard<'a, T: ?Sized> {
    // some variants omitted
}
```

--------------------------------

### Assign a new ArcShift instance

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Replaces the current ArcShift instance with a clone of the provided one. Returns an error if called recursively.

```rust
pub fn assign(&self, other: &ArcShift<T>) -> Result<(), RecursionDetected> {
    if self.recursion.get() == 0 {
        // SAFETY:
        // Getting the inner value is safe, no other thread can be accessing it now
        *unsafe { &mut *self.inner.get() } = other.clone();
        Ok(())
    } else {
        Err(RecursionDetected)
    }
}
```

--------------------------------

### Conditional DropHandler Implementation

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/deferred_panics_helper.rs.html

Selects the appropriate DropHandler implementation based on feature flags like std and nostd_unchecked_panics.

```rust
#[cfg(feature = "std")]
pub(crate) use std_drop_handler::DropHandler;

#[cfg(all(not(feature = "nostd_unchecked_panics"), not(feature = "std")))]
pub(crate) use no_std_drop_handler::DropHandler;

#[cfg(all(feature = "nostd_unchecked_panics", not(feature = "std")))]
pub(crate) use unchecked_drop_handler::DropHandler;
```

--------------------------------

### ArcShiftCellHandle Drop and Deref Implementations

Source: https://docs.rs/arcshift/0.4.4/src/arcshift/cell.rs.html

Handles the lifecycle and access logic for the ArcShiftCellHandle, including automatic reloading on drop.

```rust
impl<T: 'static + ?Sized> Drop for ArcShiftCellHandle<'_, T> {
    fn drop(&mut self) {
        let mut rec = self.cell.recursion.get();
        rec -= 1;
        if rec == 0 {
            // SAFETY:
            // There are no references to 'inner', so it's safe to obtain
            // a mutable reference.
            unsafe { (*self.cell.inner.get()).reload() };
        }
        self.cell.recursion.set(rec);
    }
}

impl<T: 'static + ?Sized> Deref for ArcShiftCellHandle<'_, T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        if self.cell.recursion.get() == 1 {
            // SAFETY:
            // We're the only owner of the ArcShiftCell, and can thus get mutable access.
            let inner: &mut ArcShift<T> = unsafe { &mut *self.cell.inner.get() };
            inner.get()
        } else {
            // SAFETY:
            // Shared access to this UnsafeCell is always allowed.
            // Actual mutable references to the 'inner' never live long enough
            // to be visible by the user of this module.
            let inner: &ArcShift<T> = unsafe { &*self.cell.inner.get() };
            inner.shared_non_reloading_get()
        }
    }
}
```

--------------------------------

### Define ArcShiftWeak struct

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShiftWeak.html?search=u32+-%3E+bool

The definition of the ArcShiftWeak struct.

```rust
pub struct ArcShiftWeak<T: ?Sized> { /* private fields */ }
```

--------------------------------

### ArcShiftWeak::upgrade

Source: https://docs.rs/arcshift/0.4.4/arcshift/struct.ArcShiftWeak.html?search=u32+-%3E+bool

Attempts to upgrade the weak reference to a full ArcShift instance. Returns Some(ArcShift<T>) if the value still exists, or None if the original ArcShift has been deallocated.

```APIDOC
## pub fn upgrade(&self) -> Option<ArcShift<T>>

### Description
Upgrade this ArcShiftWeak instance to a full ArcShift. This is required to be able to access any stored value. If the ArcShift instance has no value (because the last ArcShift instance had been deallocated), this method returns None.
```

--------------------------------

### ArcShiftCell::assign

Source: https://docs.rs/arcshift/0.4.4/arcshift/cell/struct.ArcShiftCell.html?search=

Assigns an ArcShift to the current instance.

```APIDOC
### pub fn assign(&self, other: &ArcShift<T>) -> Result<(), RecursionDetected>

Assign the given ArcShift to this instance. Returns Err if recursion is detected.
```
Tokens:
Raw