[API Proposal]: A built-in collection for weak references

[huoyaoyuan]

Background and motivation

Weak references are widely used for tracking objects meanwhile allowing them to be collected by GC. In current API, WeakReference<T> provides decent support for tracking individual objects. There is also need for weakly tracking a collection of objects effectively. Sample usages include:

• Weak event pattern, register events and automatically deregister when the handler object is collected.
• Data binding, an object listening changes to data source, or multiple-way binding of more objects, allowing each bound objects to be collected separately.

The current workarounds for managing collections of weak references including:

• Use ConditionalWeakTable. The implementation of ArrayPool<T>.Shared uses the key of ConditionalWeakTable<TKey, TValue> to weakly track references. The value slots are not used and always set to null. This can lead to more overhead for the value field storing.
• Manipulating WeakReference together with ConditionalWeakTable. Example: WeakEventManager of WPF.
• Manually manipulate lists of WeakReference. When invoked, manually check each weak reference and remove collected ones.

To simplify weak reference management and reduce potential overhead, collections of weak references are desired. BCL built-in support also provides more confidence of correctness and efficiency.

API Proposal

namespace System
{
    public class WeakCollection<T> : IEnumerable<T>
        where T : notnull // or class instead?
    {
        public void Add(T item);
        public void Trim();
        public bool Contains(T item);
        public bool Remove(T item);

        public Enumerator GetEnumerator();

        public struct Enumerator : IEnumerator<T>
        {
            public bool MoveNext();
            public T Current { get; }
        }
    }
}

API Usage

class BindableObject
{
    private readonly WeakList<BindableObject> bounded;
    void InvokeValueChanged(string newValue)
    {
        foreach (BindableObject o in bounded)
        {
            if (bounded != this)
                bounded.NotifyValueChanged(newValue);
        }
    }
}

Alternative Designs

• Implement ICollection<T>, IList<T>, or providing indexer ?
  Count and indexing are not clearly defined when some objects are collected by GC.

• Make the collection aware of GC, or make GC aware of the collection?
  Ideally, the self-cleanup should run when GC happens. For maximum memory efficiency, GC may specially recognize this collection and mark the object references inside it as "weak". When GC moves the storage of the collection, it can also compact it. This would require on-heap weak reference support, which can be very challenging.
  Making the collection aware of GC should be considerably simpler. It can use WeakReference or GCHandle to track the objects, and skips collected objects during enumeration. Implicit trimming can be triggered for add, remove, or GC collecting events.

Risks

The complexity and correctness when providing more integrated support from GC.

Tagging subscribers to this area: @dotnet/area-system-runtime
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

Weak references are widely used for tracking objects meanwhile allowing them to be collected by GC. In current API, WeakReference<T> provides decent support for tracking individual objects. There is also need for weakly tracking a collection of objects effectively. Sample usages include:

• Weak event pattern, register events and automatically deregister when the handler object is collected.
• Data binding, an object listening changes to data source, or multiple-way binding of more objects, allowing each bound objects to be collected separately.

The current workarounds for managing collections of weak references including:

• Use ConditionalWeakTable. The implementation of ArrayPool<T>.Shared uses the key of ConditionalWeakTable<TKey, TValue> to weakly track references. The value slots are not used and always set to null. This can lead to more overhead for the value field storing.
• Manipulating WeakReference together with ConditionalWeakTable. Example: WeakEventManager of WPF.
• Manually manipulate lists of WeakReference. When invoked, manually check each weak reference and remove collected ones.

To simplify weak reference management and reduce potential overhead, collections of weak references are desired. BCL built-in support also provides more confidence of correctness and efficiency.

API Proposal

namespace System
{
    public class WeakCollection<T> : IEnumerable<T>
        where T : notnull // or class instead?
    {
        public void Add(T item);
        public void Trim();
        public bool Contains(T item);
        public bool Remove(T item);

        public Enumerator GetEnumerator();

        public struct Enumerator : IEnumerator<T>
        {
            public bool MoveNext();
            public T Current { get; }
        }
    }
}

API Usage

class BindableObject
{
    private readonly WeakList<BindableObject> bounded;
    void InvokeValueChanged(string newValue)
    {
        foreach (BindableObject o in bounded)
        {
            if (bounded != this)
                bounded.NotifyValueChanged(newValue);
        }
    }
}

Alternative Designs

• Implement ICollection<T>, IList<T>, or providing indexer ?
  Count and indexing are not clearly defined when some objects are collected by GC.

• Make the collection aware of GC, or make GC aware of the collection?
  Ideally, the self-cleanup should run when GC happens. For maximum memory efficiency, GC may specially recognize this collection and mark the object references inside it as "weak". When GC moves the storage of the collection, it can also compact it. This would require on-heap weak reference support, which can be very challenging.
  Making the collection aware of GC should be considerably simpler. It can use WeakReference or GCHandle to track the objects, and skips collected objects during enumeration. Implicit trimming can be triggered for add, remove, or GC collecting events.

Risks

The complexity and correctness when providing more integrated support from GC.

Author:	huoyaoyuan
Assignees:	-
Labels:	api-suggestion, area-System.Runtime, untriaged
Milestone:	-

[teo-tsirpanis]

Instead of teaching the GC about this list, we can do what CWT does and clean-up the dead handles every time we grow the list's internal buffer.

[neon-sunset]

Strongly support weak ICollection<T> provided the objects can be compared via their comparer implementation and not by object identity.

The simplest yet quite useful use case for this is string deduplication. It is especially useful when further combined with ConditionalWeakTable<string, Regex> for weakly caching compiled regex instances, as reducing duplicate regex compilations is far more important and built-in static cache for compiled patterns is little known about and not well suitable for "heavier" scenarios.

[tannergooding]

CC. @jkotas for input here. This seems like a reasonable ask and "could" make some patterns much more efficient if it had the right runtime or GC support.

[jkotas]

There are several design decisions involved in a collection like this. For example:

• Should keys be compared by object identity (like ConditionalWeakTable), or should the collection rely on IEquatable<T> at the cost of additional overhead?
• Should it be thread-safe (like ConditionalWeakTable, with the associated overhead), or designed for single-threaded scenarios only?

It's not clear to me which set of tradeoffs this proposal is targeting.

I'd like to see a prototype demonstrating a concrete use cases where this collection provides a meaningful advantage. In my experience, custom implementations for specific scenarios - such as weak event patterns - work well enough.

make some patterns much more efficient if it had the right runtime or GC support.

I'm skeptical that special-casing this collection in the runtime or GC would result in a meaningful performance improvement. We don't have special runtime support for ConditionalWeakTable either.

. The implementation of ArrayPool.Shared uses the key of ConditionalWeakTable<TKey, TValue> to weakly track references. The value slots are not used and always set to null.

ArrayPool<T>.Shared only calls Add and enumerates the table. It doesn't rely on the hash table functionality provided by ConditionalWeakTable that is more unused overhead than the unused value slot. IIRC, ArrayPool<T>.Shared uses ConditionalWeakTable to save code size that is important for native AOT.