Struct WeakEntity 

pub struct WeakEntity<T> { /* private fields */ }

A handle to an entity that doesn’t keep it alive.

Use a WeakEntity for back-references, such as from a child view to its parent, and for callbacks that may run after the entity is released. Its update and read_with methods return a Result, which is an error once the entity has been released.

Implementations

impl<T: 'static> WeakEntity<T>

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

Returns a strong handle to the entity, or None if it has been released.

pub fn update<C, R>( &self, cx: &mut C, update: impl FnOnce(&mut T, &mut Context<'_, T>) -> R, ) -> Result<R>

where C: AppContext,

Changes the entity if it still exists. Returns an error if it has been released.

This is Entity::update for a handle that may be stale. Use it in callbacks and tasks, where the entity may have been released before the callback runs.

Panics

Panics if the entity is already being updated, in the same cases as Entity::update. A weak handle still upgrades during an update of its own entity, so it doesn’t report that case as an error.

Examples

struct Counter {
    count: usize,
}

let counter = cx.new(|_cx| Counter { count: 0 });
let weak = counter.downgrade();
assert!(weak.update(cx, |counter, _cx| counter.count += 1).is_ok());

drop(counter);
// The update that dropped the last strong handle has finished, so the counter is gone.
assert!(weak.update(cx, |counter, _cx| counter.count += 1).is_err());

pub fn update_in<C, R>( &self, cx: &mut C, update: impl FnOnce(&mut T, &mut Window, &mut Context<'_, T>) -> R, ) -> Result<R>

where C: AppContext,

Like WeakEntity::update, but also passes the Window that the entity is shown in.

Returns an error if the entity has been released, or if it isn’t shown in a window that is currently available.

pub fn read_with<C, R>( &self, cx: &C, read: impl FnOnce(&T, &App) -> R, ) -> Result<R>

where C: AppContext,

Calls read with the entity if it still exists. Returns an error if it has been released.

Use this when you only need to read the value. It works with any AppContext.

pub fn new_invalid() -> Self

Returns a weak handle that never upgrades. Use it as a placeholder until you have a real entity.

Methods from Deref<Target = AnyWeakEntity>

pub fn entity_id(&self) -> EntityId

Returns the id of the entity this handle refers to.

pub fn is_upgradable(&self) -> bool

Returns whether AnyWeakEntity::upgrade would succeed now.

Returns false once the last strong handle has been dropped, even before GPUI has released the entity.

pub fn upgrade(&self) -> Option<AnyEntity>

Returns a strong handle to the entity, or None if it has been released.

An entity whose last strong handle was dropped in the current update already returns None.

pub fn assert_released(&self)

Asserts that the entity this handle refers to has been released.

Use this in tests to find a strong handle that was leaked. A task or a subscription that still holds a strong handle makes the check fail. The check needs the leak detector, which is enabled in tests and with the leak-detection feature.

GPUI releases an entity when the update that dropped its last handle finishes. Run an update before you call this, as the example does.

Examples

let document = app.update(|cx| cx.new(|_cx| Document));
let weak = document.downgrade();
drop(document);

// The update finishes, and GPUI releases the entity.
app.update(|_cx| {});
weak.assert_released();

Debugging Leaks

If this method panics because of a leaked handle, set the LEAK_BACKTRACE environment variable to see where the handle was created: With leak detection enabled (build with GPUI_LEAK_DETECTION=1), a failure lists each leaked handle. Also set the LEAK_BACKTRACE environment variable to see where they were allocated:

GPUI_LEAK_DETECTION=1 LEAK_BACKTRACE=1 cargo test my_test

Panics

• Panics if any strong handles to the entity are still alive.
• Panics if the entity was dropped in the current update. Its resources are kept until that update finishes.

Trait Implementations

impl<T> Clone for WeakEntity<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Debug for WeakEntity<T>

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

Formats the value using the given formatter.

impl<T> Deref for WeakEntity<T>

type Target = AnyWeakEntity

The resulting type after dereferencing.

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

Dereferences the value.

impl<T> DerefMut for WeakEntity<T>

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

Mutably dereferences the value.

impl<T> Eq for WeakEntity<T>

impl<T> From<WeakEntity<T>> for AnyWeakEntity

fn from(entity: WeakEntity<T>) -> Self

Converts to this type from the input type.

impl<V: 'static + Render> From<WeakEntity<V>> for AnyWeakView

fn from(view: WeakEntity<V>) -> Self

Converts to this type from the input type.

impl<T> Hash for WeakEntity<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: 'static> Ord for WeakEntity<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<T> PartialEq for WeakEntity<T>

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T> PartialEq<Entity<T>> for WeakEntity<T>

fn eq(&self, other: &Entity<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T> PartialEq<WeakEntity<T>> for Entity<T>

fn eq(&self, other: &WeakEntity<T>) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: 'static> PartialOrd for WeakEntity<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.