Tài liệu

Pool đối tượng

Thời gian đọc 7 phút Gói: Nalix.Framework
Trên trang này

Không gian tên: Nalix.Framework.Memory.Objects (và Nalix.Framework.Options)
Assembly: Nalix.Framework

ObjectPoolManager ([Injectable(typeof(IObjectPoolManager))] public sealed partial class ObjectPoolManager : IObjectPoolManager, IDisposable) quản lý các instance lớp có thể tái sử dụng, triển khai IPoolable, trên toàn bộ stack Nalix (packet, PacketContext<T>, PacketSender, ObjectMap<K,V>, vỏ BufferLease, và event args của socket).

Kiến trúc pool đối tượng

Architecture Diagram
flowchart TD
    Req(["ObjectPoolManager.Get<T>()"]) --> TypeId["Lookup PoolType<T>.Id (Flat Array _pools[id])"]
    TypeId --> TLC{"ThreadCacheDepth > 0 & Slot Has Item?"}
    TLC -->|Yes| HitTLC["Pop from ThreadLocalCache<T>"]
    TLC -->|No| Bucket{"TypePool Stack Has Item?"}
    Bucket -->|Yes| HitBucket["Pop from TypePool Stack"]
    Bucket -->|No| Create["Create via new T() (Cache Miss)"]

    HitTLC --> RentHook{"T is IPoolRentable?"}
    HitBucket --> RentHook
    Create --> RentHook
    RentHook -->|Yes| CallOnRent["Call rentable.OnRent()"] --> Ret(["Return T"])
    RentHook -->|No| Ret

    RetCall(["ObjectPoolManager.Return<T>(obj)"]) --> Reset["obj.ResetForPool() inside TypePool/ThreadLocalCache"]
    Reset --> Store["Store in ThreadLocalCache (if enabled) or TypePool up to MaxCapacity"]

Ánh xạ mã nguồn

  • src/Nalix.Abstractions/IPoolable.cs
  • src/Nalix.Abstractions/IObjectPoolManager.cs
  • src/Nalix.Framework/Memory/Objects/ObjectPoolManager.cs
  • src/Nalix.Framework/Memory/Objects/ObjectPoolManager.Cleanup.cs
  • src/Nalix.Framework/Memory/Objects/ObjectPoolManager.Report.cs
  • src/Nalix.Framework/Memory/Objects/TypedObjectPool.cs
  • src/Nalix.Framework/Options/ObjectPoolOptions.cs

Hợp đồng lõi (IPoolable & IPoolRentable)

namespace Nalix.Abstractions;

public interface IPoolable
{
    void ResetForPool();
}

public interface IPoolRentable
{
    void OnRent();
}
  • IPoolable.ResetForPool(): Được gọi tự động khi một đối tượng được trả về pool (Return<T>(obj)). Các triển khai phải xóa tham chiếu và đặt lại các trường có thể thay đổi.
  • IPoolRentable.OnRent(): Hook tùy chọn được ObjectPoolManager.Get<T>() gọi ngay trước khi trả instance đã thuê về cho người gọi.
  • Chống trả về hai lần (IPoolStateTracked): Các đối tượng triển khai IPoolStateTracked (MarkRented() / TryMarkReturned()) được kiểm tra khi Return<T>(obj), nên việc trả trùng lặp sẽ bị từ chối an toàn (TotalRejectedReturnCount).

Tham chiếu API ObjectPoolManager

Cấu hình tĩnh

Thành phầnChữ kýMô tả
Sharedpublic static ObjectPoolManager Shared { get; }Trả về ObjectPoolManager toàn cục đã được cấu hình (ném InvalidOperationException nếu truy cập trước khi gọi Configure).
Configurepublic static void Configure(ObjectPoolManager manager)Đặt instance ObjectPoolManager.Shared cho toàn tiến trình (được NetworkApplicationBuilder nối tự động).

Constructor, thuộc tính & phương thức

Thành phầnChữ kýMô tả
ObjectPoolManager()public ObjectPoolManager()Tải ObjectPoolOptions từ ConfigurationManager.Instance và lập lịch tác vụ định kỳ obj.trim nếu EnableObjectTrimming là true.
ObjectPoolManager(ObjectPoolOptions)public ObjectPoolManager(ObjectPoolOptions config)Khởi tạo trình quản lý pool với ObjectPoolOptions tường minh.
PoolCount / PeakPoolCountintSố lượng pool theo kiểu đang quản lý hiện tại và cao nhất.
TotalGetOperations / TotalReturnOperationslongBộ đếm trọn đời của các thao tác Get<T>() và Return<T>(obj).
TotalCacheHits / TotalCacheMisseslongTổng số lần trúng pool so với cấp phát mới (new T()).
CacheHitRatedoubleTỷ lệ trúng cache tổng thể theo phần trăm (0.0..100.0).
UptimeTimeSpanThời gian đã trôi qua kể từ khi manager được tạo hoặc ResetStatistics() được gọi.
UnhealthyPoolCountintSố pool bị đánh dấu không lành mạnh trong lần PerformHealthCheck() gần nhất.
Get<T>()public T Get<T>() where T : IPoolable, new()Thuê hoặc tạo instance T qua tra cứu mảng phẳng PoolType<T>.Id (cấp phát trước DefaultPreallocate mục khi truy cập lần đầu một kiểu mới).
Return<T>(T)public void Return<T>(T obj) where T : IPoolableĐặt lại obj (ResetForPool()) và trả nó về pool (ném ArgumentNullException nếu obj là null).
GetTypedPool<T>()public TypedObjectPool<T> GetTypedPool<T>() where T : IPoolable, new()Trả về adapter TypedObjectPool<T> gắn với manager này.
Prealloc<T>(int)public int Prealloc<T>(int count) where T : IPoolable, new()Cấp phát trước count instance vào pool của T (count > 0) và trả về số instance đã thêm.
SetMaxCapacity<T>(int)public bool SetMaxCapacity<T>(int maxCapacity) where T : IPoolableĐặt dung lượng giữ lại tối đa cho pool của T (maxCapacity >= 0).
GetTypeInfo<T>()public Dictionary<string, object> GetTypeInfo<T>() where T : IPoolableTrả về từ điển chỉ số (AvailableCount, MaxCapacity, TotalGets, TotalReturns, CacheHitRate, Outstanding, PeakOutstanding, Status, và các percentile vòng đời khi EnableDiagnostics = true).
ClearPool<T>() / ClearAllPools()public int ClearPool<T>() / public int ClearAllPools()Xóa các instance trong pool và trả về số đối tượng đã loại bỏ.
PerformHealthCheck()public int PerformHealthCheck()Đánh giá tỷ lệ miss theo cửa sổ trên các pool đang hoạt động và trả về số pool không lành mạnh.
ResetMetrics() / ResetStatistics()public void ResetMetrics() / public void ResetStatistics()Đặt lại bộ đếm toàn cục và theo từng pool.
GenerateReport() / WriteReportDatapublic string GenerateReport() / public void WriteReportData(Utf8JsonWriter writer)Tạo báo cáo văn bản dễ đọc hoặc JSON có cấu trúc.

ObjectPoolOptions (Nalix.Framework.Options)

Được cấu hình qua [ObjectPool] trong default.ini hoặc builder.Configure<ObjectPoolOptions>(...):

Thuộc tínhKiểuMặc địnhRàng buộcMô tả
EnableDiagnosticsboolfalse—Bật theo dõi PoolSentinel cho vòng đời đối tượng (Avg/p95/Max) và các lần thuê bất thường kéo dài.
EnableMetricsbooltrue—Bật bộ đếm hit/miss và Outstanding nhẹ, dùng nguyên tử (an toàn cho production).
CaptureStackTracesboolfalse—Ghi stack trace cấp phát khi Get<T>() nếu EnableDiagnostics = true (tốn kém; chỉ dùng khi gỡ lỗi rò rỉ).
SuspiciousThresholdSecondsint30[ValueRange(0, 3600)]Ngưỡng tính bằng giây; sau thời gian này, đối tượng chưa được trả sẽ bị đánh dấu đáng ngờ.
EnableLeakDetectionboolfalse—Dùng finalizer của PoolSentinel để phát hiện đối tượng đã thuê bị GC thu hồi mà không gọi Return<T>() (yêu cầu EnableDiagnostics = true để PoolSentinel được gắn khi Get<T>()).
LifetimeReservoirSizeint64[ValueRange(16, 1024)]Số mẫu thời lượng thuê gần nhất giữ cho mỗi pool, dùng để tính p95LifetimeMs.
EnableObjectTrimmingbooltrue—Lập lịch tác vụ định kỳ TaskManager (obj.trim) để giải phóng các đối tượng pool đang rảnh.
TrimIntervalMinutesint5[ValueRange(1, 60)]Khoảng thời gian (phút) giữa các chu kỳ cắt tỉa thông thường.
DeepTrimIntervalMinutesint30[ValueRange(5, 120)]Khoảng thời gian (phút) giữa các chu kỳ cắt tỉa sâu/mạnh.
BaseKeepPercentageint75[ValueRange(50, 90)]Phần trăm dung lượng được giữ lại trong chu kỳ cắt tỉa thông thường.
DeepTrimPercentageint25[ValueRange(10, 45)]Phần trăm dung lượng được giữ lại trong chu kỳ cắt tỉa sâu.
TrimDecayFactordouble0.5[ValueRange(0.1, 1.0)]Tỷ lệ đối tượng dư thừa bị loại bỏ mỗi chu kỳ cắt tỉa (suy giảm theo cấp số nhân).
HotHitRateThresholddouble85.0[ValueRange(75.0, 98.0)]Tỷ lệ trúng (phần trăm) mà trên đó một pool được coi là “nóng” và chỉ được cắt tỉa nhẹ.
MinimumKeepObjectsint8[ValueRange(4, 64)]Ngưỡng tối thiểu luôn được giữ trong mỗi pool khi cắt tỉa.
DefaultMaxPoolSizeint2048[ValueRange(1024, 1_000_000)]Dung lượng tối đa mặc định cho các pool theo kiểu mới tạo.
DefaultPreallocateint8[ValueRange(0, 1_000_000)]Số instance được cấp phát trước khi một pool theo kiểu được tạo lần đầu.
ThreadCacheDepthint0[ValueRange(0, 4)]Độ sâu ThreadLocalCache<T> theo từng luồng (0 = tắt mặc định để các continuation async/await chạy trên các luồng ThreadPool khác nhau không làm kẹt đối tượng trong pool).

ListPool<T> (Nalix.Framework.Memory.Pools)

ListPool<T> (src/Nalix.Framework/Memory/Pools/ListPool.cs) là pool an toàn đa luồng, chứa các instance List<T> có thể tái sử dụng. ListPool<T>.Instance là singleton dùng chung (kích thước pool tối đa mặc định 1024, dung lượng ban đầu 16); constructor public ListPool(int maxPoolSize, int initialCapacity) tạo một pool tùy chỉnh.

  • Rent(int minimumCapacity = 0) / Return(List<T> list, bool clearItems = true) — thuê và trả một list.
  • Prealloc(int count, int capacity = 0), Trim(int maximumSize = 0), Clear() — bảo trì pool.
  • AvailableCount, CreatedCount, RentedCount, TotalRentOperations, TotalReturnOperations, TrimmedCount, UptimeMs, GetStatistics(), ResetStatistics() — thống kê.

API liên quan