Gcoder.Collections 1.0.2

Gcoder.Collections

Thư viện collection hiệu năng cao cho .NET 9, cung cấp hai cấu trúc dữ liệu chuyên biệt: Sorted Dictionary (giống Redis ZSET) và Timed Collection (time wheel-based expiration).

Tính năng

1. ISortedDictionary<TKey, TValue>

Sorted dictionary sử dụng Skip List + Hash Map bên trong, mô phỏng Redis Sorted Set (ZSET). Hỗ trợ đầy đủ thao tác rank, range by score, range by rank.

Ví dụ:

using Gcoder.Collections;

var dict = ISortedDictionary<string, int>.Create();

dict.Add("player1", 1500);
dict.Add("player2", 2000);
dict.Add("player3", 1200);

// Lấy top 2 người chơi điểm cao nhất
var top2 = dict.RangeByRank(0, 1); // (player3,1200), (player1,1500)

// Đếm số người chơi trong khoảng điểm [1200, 1800]
int count = dict.CountByScore(1200, 1800); // 2

// Xoá người chơi có điểm < 1500
int removed = dict.RemoveRangeByScore(int.MinValue, 1499); // 1

2. ITimedCollection<TKey, TValue>

Time wheel-based collection với cơ chế tự động hết hạn (expiration). Sử dụng Hierarchical Time Wheel 3 tầng, hỗ trợ hàng triệu object với O(1) per operation.

Có 2 phiên bản:

a) Phiên bản Thread-Safe (NewTimeSortSet)

• Sử dụng ReaderWriterLockSlim + background timer thread 10ms
• An toàn cho đa luồng
• OnExpired / OnRemoved fire từ background thread
• Tick() không có tác dụng (no-op) — timer đã tự chạy

using Gcoder.Collections;

using var collection = ITimedCollection<string, string>.NewTimeSortSet();

// Callback khi object hết hạn
collection.OnExpired += items =>
{
    foreach (var (key, value) in items)
        Console.WriteLine($"Expired: {key}");
};

// Thêm object hết hạn sau 5 giây
collection.AddOrUpdate("session:123", "data", TimeSpan.FromSeconds(5));

// Hoặc dùng absolute time
collection.AddOrUpdate("session:456", "data",
    DateTimeOffset.UtcNow.AddSeconds(10));

// Xoá chủ động (kích hoạt OnRemoved)
collection.Remove("session:123");

b) Phiên bản Single-Thread (NewTimeSortSetSingleThread)

• Không ReaderWriterLockSlim, không background timer → zero lock overhead
• Expiration lười (lazy): kiểm tra trên mỗi AddOrUpdate / Remove / Count / Tick
• OnExpired / OnRemoved fire đồng bộ trên thread gọi
• Chỉ dùng khi toàn bộ truy cập từ 1 thread
• Cần gọi Tick() định kỳ (vd: mỗi frame trong game loop) nếu collection có thể idle lâu

using Gcoder.Collections;

using var collection = ITimedCollection<string, string>.NewTimeSortSetSingleThread();

collection.OnExpired += items =>
{
    foreach (var (key, value) in items)
        Console.WriteLine($"Expired: {key}");
};

collection.AddOrUpdate("session:123", "data", TimeSpan.FromSeconds(5));

// Trong game loop / update loop
while (running)
{
    collection.Tick(); // ← đẩy wheel, dọn expire mà không cần add/remove
    // ... logic game
}

So sánh 2 phiên bản:

Cài đặt

dotnet add package Gcoder.Collections --version 1.0.2

Hoặc tham khảo source trực tiếp từ GitHub.

Yêu cầu

• .NET 9+

Thread Safety

• ISortedDictionary (DictionaryScore): Không thread-safe. Cần lock bên ngoài nếu truy cập đa luồng.
• ITimedCollection (NewTimeSortSet): Có thread-safe. Dùng ReaderWriterLockSlim + background timer.
• ITimedCollection (NewTimeSortSetSingleThread): Không thread-safe. Tối ưu đơn luồng, lazy expiration.

License

MIT