fix: Adds GetClients to map iterators (#1574)

### Summary

Eliminates `IPooledEnumerable<NetState>` and `eable.Free()` from `Map` for clients. This drastically simplifies code that iterates in range, for example:

```cs
foreach (var m in m.GetClientsInRange(5))
{
}
```
The code above no longer requires an eable and calling `Free()`.

Projects/Server/Maps/Map.ClientEnumerator.cs

@@ -0,0 +1,270 @@
+/*************************************************************************
+ * ModernUO                                                              *
+ * Copyright 2019-2023 - ModernUO Development Team                       *
+ * Email: hi@modernuo.com                                                *
+ * File: Map.ClientEnumerator.cs                                         *
+ *                                                                       *
+ * This program is free software: you can redistribute it and/or modify  *
+ * it under the terms of the GNU General Public License as published by  *
+ * the Free Software Foundation, either version 3 of the License, or     *
+ * (at your option) any later version.                                   *
+ *                                                                       *
+ * You should have received a copy of the GNU General Public License     *
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>. *
+ *************************************************************************/
+
+using System;
+using System.Runtime.CompilerServices;
+using Server.Collections;
+using Server.Network;
+
+namespace Server;
+
+public partial class Map
+{
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientAtEnumerable GetClientsAt(Point3D p) => GetClientsAt(new Point2D(p.X, p.Y));
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientAtEnumerable GetClientsAt(int x, int y) => GetClientsAt(new Point2D(x, y));
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientAtEnumerable GetClientsAt(Point2D p) => new(this, p);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInRange(Point3D p) => GetClientsInRange(p, Core.GlobalMaxUpdateRange);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInRange(Point3D p, int range) =>
+        GetClientsInRange(p.m_X, p.m_Y, range);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInRange(Point2D p) => GetClientsInRange(p, Core.GlobalMaxUpdateRange);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInRange(Point2D p, int range) =>
+        GetClientsInRange(p.m_X, p.m_Y, range);
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInRange(int x, int y, int range) =>
+        GetClientsInBounds(new Rectangle2D(x - range, y - range, range * 2 + 1, range * 2 + 1));
+
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public ClientBoundsEnumerable GetClientsInBounds(Rectangle2D bounds, bool makeBoundsInclusive = false) =>
+        new(this, bounds, makeBoundsInclusive);
+
+    public ref struct ClientAtEnumerable
+    {
+        public static ClientAtEnumerable Empty
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => new();
+        }
+
+        private readonly Map _map;
+        private readonly Point2D _location;
+
+        public ClientAtEnumerable(Map map, Point2D loc)
+        {
+            _map = map;
+            _location = loc;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ClientAtEnumerator GetEnumerator() => new(_map, _location);
+    }
+
+    public ref struct ClientAtEnumerator
+    {
+        private bool _started;
+        private Point2D _location;
+        private ref readonly ValueLinkList<NetState> _linkList;
+        private int _version;
+        private NetState _current;
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public ClientAtEnumerator(Map map, Point2D loc)
+        {
+            _started = false;
+            _location = loc;
+            _linkList = ref map.GetRealSector(loc.m_X, loc.m_Y).Clients;
+            _version = 0;
+            _current = null;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool MoveNext()
+        {
+            ref var loc = ref _location;
+            NetState current;
+            Mobile m;
+
+            if (!_started)
+            {
+                current = _linkList._first;
+                _started = true;
+                _version = _linkList.Version;
+
+                m = current.Mobile;
+                if (m?.Deleted == false && m.X == loc.m_X && m.Y == loc.m_Y)
+                {
+                    _current = current;
+                    return true;
+                }
+            }
+            else if (_linkList.Version != _version)
+            {
+                throw new InvalidOperationException(CollectionThrowStrings.InvalidOperation_EnumFailedVersion);
+            }
+            else
+            {
+                current = _current;
+            }
+
+            while (current != null)
+            {
+                current = current.Next;
+
+                m = current.Mobile;
+                if (m?.Deleted == false && m.X == loc.m_X && m.Y == loc.m_Y)
+                {
+                    _current = current;
+                    return true;
+                }
+            }
+
+            return false;
+        }
+
+        public NetState Current
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => _current;
+        }
+    }
+
+    public ref struct ClientBoundsEnumerable
+    {
+        public static ClientBoundsEnumerable Empty
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => new(null, Rectangle2D.Empty, false);
+        }
+
+        private readonly Map _map;
+        private readonly Rectangle2D _bounds;
+        private readonly bool _makeBoundsInclusive;
+
+        public ClientBoundsEnumerable(Map map, Rectangle2D bounds, bool makeBoundsInclusive)
+        {
+            _map = map;
+            _bounds = bounds;
+            _makeBoundsInclusive = makeBoundsInclusive;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public MobileEnumerator GetEnumerator() => new(_map, _bounds, _makeBoundsInclusive);
+    }
+
+    public ref struct MobileEnumerator
+    {
+        private readonly Map _map;
+        private readonly int _sectorStartX;
+        private readonly int _sectorEndX;
+        private readonly int _sectorEndY;
+        private Rectangle2D _bounds;
+
+        private int _currentSectorX;
+        private int _currentSectorY;
+
+        private ref readonly ValueLinkList<NetState> _linkList;
+        private int _currentVersion;
+        private NetState _current;
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public MobileEnumerator(Map map, Rectangle2D bounds, bool makeBoundsInclusive)
+        {
+            _map = map;
+            _bounds = bounds;
+
+            if (makeBoundsInclusive)
+            {
+                ++bounds.Width;
+                ++bounds.Height;
+            }
+
+            _bounds = bounds;
+
+            map.CalculateSectors(bounds, out _sectorStartX, out var _sectorStartY, out _sectorEndX, out _sectorEndY);
+
+            // We start the X sector one short because it gets incremented immediately in MoveNext()
+            _currentSectorX = _sectorStartX - 1;
+            _currentSectorY = _sectorStartY;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool MoveNext()
+        {
+            var map = _map;
+
+            if (map == null)
+            {
+                return false;
+            }
+
+            Mobile m;
+            NetState current = _current;
+            ref Rectangle2D bounds = ref _bounds;
+            var currentSectorX = _currentSectorX;
+            var currentSectorY = _currentSectorY;
+            var sectorEndX = _sectorEndX;
+            var sectorEndY = _sectorEndY;
+
+            while (true)
+            {
+                current = current?.Next;
+
+                while (current == null)
+                {
+                    // Move to next sector
+                    if (currentSectorX < sectorEndX)
+                    {
+                        _currentSectorX = ++currentSectorX;
+                    }
+                    else if (currentSectorY < sectorEndY)
+                    {
+                        _currentSectorX = currentSectorX = _sectorStartX;
+                        _currentSectorY = ++currentSectorY;
+                    }
+                    else
+                    {
+                        // Ran out of sectors
+                        return false;
+                    }
+
+                    _linkList = ref map.GetRealSector(currentSectorX, currentSectorY).Clients;
+                    _currentVersion = _linkList.Version;
+                    current = _linkList._first;
+                }
+
+                if (_linkList.Version != _currentVersion)
+                {
+                    throw new InvalidOperationException(CollectionThrowStrings.InvalidOperation_EnumFailedVersion);
+                }
+
+                m = current.Mobile;
+                if (m?.Deleted == false && bounds.Contains(m.Location))
+                {
+                    _current = current;
+                    return true;
+                }
+            }
+        }
+
+        public NetState Current
+        {
+            [MethodImpl(MethodImplOptions.AggressiveInlining)]
+            get => _current;
+        }
+    }
+}

Projects/Server/Maps/Map.ItemEnumerator.cs

@@ -84,8 +84,8 @@ public partial class Map
             get => new();
         }
 
-        private Map _map;
-        private Point2D _location;
+        private readonly Map _map;
+        private readonly Point2D _location;
 
         public ItemAtEnumerable(Map map, Point2D loc)
         {

Projects/Server/Maps/Map.MobileEnumerator.cs

@@ -84,8 +84,8 @@ public partial class Map
             get => new();
         }
 
-        private Map _map;
-        private Point2D _location;
+        private readonly Map _map;
+        private readonly Point2D _location;
 
         public MobileAtEnumerable(Map map, Point2D loc)
         {

Projects/Server/Maps/Map.cs

@@ -873,14 +873,6 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
     public IPooledEnumerable<IEntity> GetObjectsInBounds(Rectangle2D bounds) =>
         PooledEnumeration.GetEntities(this, bounds);
 
-    public IPooledEnumerable<NetState> GetClientsInRange(Point3D p) => GetClientsInRange(p, Core.GlobalMaxUpdateRange);
-
-    public IPooledEnumerable<NetState> GetClientsInRange(Point3D p, int range) =>
-        GetClientsInBounds(new Rectangle2D(p.m_X - range, p.m_Y - range, range * 2 + 1, range * 2 + 1));
-
-    public IPooledEnumerable<NetState> GetClientsInBounds(Rectangle2D bounds) =>
-        PooledEnumeration.GetClients(this, bounds);
-
     public bool CanFit(
         Point3D p, int height, bool checkBlocksFit = false, bool checkMobiles = true,
         bool requireSurface = true
@@ -1426,12 +1418,10 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
     public class Sector
     {
         // TODO: Can we avoid this?
-        private static readonly List<Mobile> m_DefaultMobileList = new();
-        private static readonly List<NetState> m_DefaultClientList = new();
         private static readonly List<BaseMulti> m_DefaultMultiList = new();
         private static readonly List<Region> m_DefaultRectList = new();
         private bool m_Active;
-        private List<NetState> _clients;
+        private ValueLinkList<NetState> _clients;
         private ValueLinkList<Item> _items;
         private ValueLinkList<Mobile> _mobiles;
         private List<BaseMulti> _multis;
@@ -1453,7 +1443,7 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
 
         internal ref readonly ValueLinkList<Item> Items => ref _items;
 
-        public List<NetState> Clients => _clients ?? m_DefaultClientList;
+        internal ref readonly ValueLinkList<NetState> Clients => ref _clients;
 
         public bool Active => m_Active && Owner != Internal;
 
@@ -1465,7 +1455,26 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
 
         public void OnClientChange(NetState oldState, NetState newState)
         {
-            Utility.Replace(ref _clients, oldState, newState);
+            var count = _clients.Count;
+
+            if (oldState != null)
+            {
+                _clients.Remove(oldState);
+            }
+
+            if (newState != null)
+            {
+                _clients.AddLast(newState);
+            }
+
+            if (_clients.Count == 0 && count > 0)
+            {
+                Owner.DeactivateSectors(X, Y);
+            }
+            else if (count == 0 && _clients.Count > 0)
+            {
+                Owner.ActivateSectors(X, Y);
+            }
         }
 
         public void OnEnter(Item item)
@@ -1484,7 +1493,7 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
 
             if (mob.NetState != null)
             {
-                Utility.Add(ref _clients, mob.NetState);
+                _clients.AddLast(mob.NetState);
 
                 Owner.ActivateSectors(X, Y);
             }
@@ -1496,7 +1505,7 @@ public sealed partial class Map : IComparable<Map>, ISpanFormattable, ISpanParsa
 
             if (mob.NetState != null)
             {
-                Utility.Remove(ref _clients, mob.NetState);
+                _clients.Remove(mob.NetState);
 
                 Owner.DeactivateSectors(X, Y);
             }

Projects/Server/Maps/PooledEnumeration.cs

@@ -19,7 +19,6 @@ using System.Collections.Generic;
 using System.Linq;
 using Server.Collections;
 using Server.Items;
-using Server.Network;
 
 namespace Server;
 
@@ -33,34 +32,16 @@ public static class PooledEnumeration
 
     static PooledEnumeration()
     {
-        ClientSelector = SelectClients;
         EntitySelector = SelectEntities;
         MultiSelector = SelectMultis;
         MultiTileSelector = SelectMultiTiles;
     }
 
-    public static Selector<NetState> ClientSelector { get; set; }
     public static Selector<IEntity> EntitySelector { get; set; }
     public static Selector<Mobile> MobileSelector { get; set; }
     public static Selector<BaseMulti> MultiSelector { get; set; }
     public static Selector<StaticTile[]> MultiTileSelector { get; set; }
 
-    public static IEnumerable<NetState> SelectClients(Map.Sector s, Rectangle2D bounds)
-    {
-        var clients = new List<NetState>(s.Clients.Count);
-        foreach (var client in s.Clients)
-        {
-            var m = client.Mobile;
-
-            if (m?.Deleted == false && bounds.Contains(m.Location))
-            {
-                clients.Add(client);
-            }
-        }
-
-        return clients;
-    }
-
     public static IEnumerable<IEntity> SelectEntities(Map.Sector s, Rectangle2D bounds)
     {
         var entities = new List<IEntity>(s.Mobiles.Count + s.Items.Count);
@@ -145,9 +126,6 @@ public static class PooledEnumeration
         }
     }
 
-    public static PooledEnumerable<NetState> GetClients(Map map, Rectangle2D bounds) =>
-        PooledEnumerable<NetState>.Instantiate(map, bounds, ClientSelector ?? SelectClients);
-
     public static PooledEnumerable<IEntity> GetEntities(Map map, Rectangle2D bounds) =>
         PooledEnumerable<IEntity>.Instantiate(map, bounds, EntitySelector ?? SelectEntities);