Struct RefMut

pub struct RefMut<'a, T: IdOrdItem>
where
    T::Key<'a>: Hash,
{ /* private fields */ }

A mutable reference to an IdOrdMap entry.

This is a wrapper around a &mut T that panics when dropped, if the borrowed value’s key has changed since the wrapper was created.

Change detection

It is illegal to change the keys of a borrowed &mut T. RefMut attempts to enforce this invariant, and as part of that, it requires that the key type implement Hash.

RefMut stores the Hash output of keys at creation time, and recomputes these hashes when it is dropped or when Self::into_ref is called. If a key changes, there’s a small but non-negligible chance that its hash value stays the same¹. In that case, the map will no longer function correctly and might panic on access. This will not introduce memory safety issues, however.

It is also possible to deliberately write pathological Hash implementations that collide more often. (Don’t do this.)

Also, RefMut’s hash detection will not function if mem::forget is called on it. If a key is changed and mem::forget is then called on the RefMut, the IdOrdMap will no longer function correctly and might panic on access. This will not introduce memory safety issues, however.

The issues here are similar to using interior mutability (e.g. RefCell or Mutex) to mutate keys in a regular HashMap.

---

1. The output of Hash is a u64, so the probability of an individual hash colliding by chance is 1/2⁶⁴. Due to the birthday problem, the probability of a collision by chance reaches 10⁻⁶ within around 6 × 10⁶ elements. ↩

Implementations

impl<'a, T: IdOrdItem> RefMut<'a, T>

where T::Key<'a>: Hash,

pub fn into_ref(self) -> &'a T

Converts this RefMut into a &'a T.

impl<'a, T: IdOrdItem> RefMut<'a, T>

where for<'k> T::Key<'k>: Hash,

pub fn reborrow<'b>(&'b mut self) -> RefMut<'b, T>

Borrows self into a shorter-lived RefMut.

This RefMut will also check hash equality on drop.

Note: currently, due to limitations in the Rust borrow checker, this effectively requires that T: 'static. Relaxing this requirement should be possible in principle.

Trait Implementations

impl<'a, T: IdOrdItem + Debug> Debug for RefMut<'a, T>

where T::Key<'a>: Hash,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T: IdOrdItem> Deref for RefMut<'a, T>

where T::Key<'a>: Hash,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<'a, T: IdOrdItem> DerefMut for RefMut<'a, T>

where T::Key<'a>: Hash,

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<'a, T: IdOrdItem> Drop for RefMut<'a, T>

where T::Key<'a>: Hash,

fn drop(&mut self)

Executes the destructor for this type.