How does List<T> work internally? Explain capacity and growth, the cost of Add, Insert and Remove, why modifying a list during foreach throws, and how CollectionsMarshal.AsSpan and EnsureCapacity help in hot paths.

1. The implementation (simplified)

public class List<T> : IList<T>, IReadOnlyList<T>, IList
{
    internal T[] _items;
    internal int _size;
    internal int _version;

    public void Add(T item)
    {
        _version++;
        T[] array = _items;
        int size = _size;
        if ((uint)size < (uint)array.Length) { _size = size + 1; array[size] = item; }
        else AddWithResize(item);           // cold path, not inlined
    }

    private void Grow(int capacity)
    {
        int newCapacity = _items.Length == 0 ? 4 : 2 * _items.Length;
        if ((uint)newCapacity > Array.MaxLength) newCapacity = Array.MaxLength;
        if (newCapacity < capacity) newCapacity = capacity;
        Capacity = newCapacity;             // allocates and Array.Copy
    }
}

The hot Add path is small enough to inline; resizing is moved to a separate method so the common case stays fast.

2. Amortised analysis

With doubling, the total copy work to reach n elements is 4 + 8 + 16 + ... + n/2 < n. So n adds cost O(n) total — amortised O(1) each — even though an individual Add can cost O(n). Growth factors matter: 1.5× (used by some other runtimes) wastes less memory but copies more; .NET chose 2×.

Latency-sensitive code should care about the worst case: a single Add that triggers a copy of a 1 GB backing array can take long enough to show up as a latency spike, plus an LOH allocation.

3. Removal and GC

RemoveAt shifts elements left with Array.Copy and then sets the last slot to default if T contains references (RuntimeHelpers.IsReferenceOrContainsReferences<T>()), so removed objects can be garbage collected. Clear() does the same for the whole array. For unmanaged T (e.g. int), Clear just sets _size = 0 — O(1).

Note that removing items never shrinks capacity: a list that once held 1 million items keeps a 1-million-slot array until TrimExcess() or Capacity is set.

4. The struct enumerator and version checks

public struct Enumerator : IEnumerator<T>
{
    private readonly List<T> _list;
    private int _index;
    private readonly int _version;
    private T? _current;

    public bool MoveNext()
    {
        if (_version == _list._version && (uint)_index < (uint)_list._size)
        { _current = _list._items[_index++]; return true; }
        return MoveNextRare();   // throws if version changed
    }
}

Because the enumerator is a struct and MoveNext is small, foreach over a List<T> variable is nearly as fast as a for loop. Through IEnumerable<T>, it is boxed and calls become interface calls.

5. ForEach, LINQ and ConvertAll

• list.ForEach(action) checks the version too and throws if the action modifies the list; it allocates a delegate (closure if capturing). A plain foreach is usually clearer.
• ConvertAll pre-sizes the result — slightly better than Select(...).ToList() historically, though LINQ's ToList now pre-sizes for IList<T> sources too.
• LINQ's Count(), ElementAt(), Last() detect IList<T> and use O(1) paths.

6. Thread safety

List<T> is safe for multiple concurrent readers if nobody writes. Any concurrent write can:

• Lose additions (two threads write to the same slot).
• Throw IndexOutOfRangeException during a resize race.
• Corrupt _size so Count doesn't match the data.

Use a lock, ImmutableList<T>/ImmutableArray<T> snapshots, or ConcurrentQueue/ConcurrentBag/Channel<T> depending on the access pattern.

7. Interaction with EF Core and serialisation

• EF Core materialises results into List<T> via ToListAsync, which grows as rows arrive (it doesn't know the count). For huge result sets, stream with AsAsyncEnumerable() instead.
• System.Text.Json deserialises arrays into List<T> by default, growing as it reads.

Try it yourself

1. Print Capacity after each Add from 0 to 100 items.
2. Benchmark adding 1 million items with and without initial capacity, with [MemoryDiagnoser].
3. Benchmark Insert(0, x) vs Add(x) + Reverse() for 100,000 items.
4. Hold a CollectionsMarshal.AsSpan span, add items until the list resizes, write through the span, and observe the lost update.

using System.Runtime.InteropServices;

// 1. Pre-size when the count is known
var readings = new List<double>(capacity: expectedCount);

// 2. Remove safely in one pass
readings.RemoveAll(r => double.IsNaN(r));

// 3. This throws InvalidOperationException
// foreach (var r in readings)
//     if (r < 0) readings.Remove(r);

// 4. Work on the backing array without copies
Span<double> span = CollectionsMarshal.AsSpan(readings);
for (int i = 0; i < span.Length; i++)
    span[i] *= 1.1;                       // no list indexer overhead
// readings.Add(1);  // after this, 'span' would point at the old array

// 5. Mutable struct elements
List<Point> pts = [new(1, 2)];
// pts[0].X = 5;                          // CS1612: indexer returns a copy
CollectionsMarshal.AsSpan(pts)[0].X = 5;  // edits in place

// 6. Fill through a span (.NET 8+)
var buffer = new List<int>();
CollectionsMarshal.SetCount(buffer, 1000);
CollectionsMarshal.AsSpan(buffer).Fill(-1);

struct Point(int x, int y) { public int X = x; public int Y = y; }