jobjectpool

# JObjectPool - Thread-Safe Object Pooling Thread-safe, lock-free generic object pooling for Unity using CAS operations. Works with job system and async operations. ## When to Use - Frequently instantiated objects (bullets, enemies, effects) - Reducing GC during gameplay - Multi-threaded object reuse (safe from any thread) - High-frequency object lifecycle operations ## Core API ### Constructor ```csharp new JObjectPool<T>( int maxSize = 64, // Maximum pooled objects (excess discarded) Action<T> onRent = null, // Called when renting (for initialization) Action<T> onReturn = null // Called when returning (for cleanup) ) ``` Note: `T` must be a reference type with a parameterless constructor (`where T : class, new()`). ### Methods - `.Rent()` - Get object from pool or create new - `.Return(T obj)` - Return object to pool (null values ignored) - `.Clear()` - Remove all pooled objects - `.Prewarm(int count)` - Pre-allocate objects (won't exceed maxSize) - `.Count` - Current available count (approximate, thread-safe) ### Static Access - `JObjectPool.Shared<T>()` - Global shared pool per type (default config: maxSize=64) ## Patterns ### Basic Pool ```csharp var pool = new JObjectPool<Bullet>(maxSize: 100); var bullet = pool.Rent(); // ... use bullet ... pool.Return(bullet); ``` ### With Initialization on Rent ```csharp var pool = new JObjectPool<Enemy>( maxSize: 50, onRent: static enemy => enemy.Reset() ); ``` ### Reset State on Return (RECOMMENDED) ```csharp var pool = new JObjectPool<List<int>>( maxSize: 32, onReturn: static list => list.Clear() ); ``` ### Prewarm During Loading ```csharp var pool = new JObjectPool<Effect>(); pool.Prewarm(50); // Pre-create during loading screen ``` ### Shared Pool (Simple Objects) ```csharp // Good for simple reusable objects without custom callbacks var sb = JObjectPool.Shared<StringBuilder>().Rent(); sb.Append("Hello"); sb.Clear(); // Clean up before returning JObjectPool.Shared<StringBuilder>().Return(sb); ``` ## Game Patterns (Zero-GC) ### Bullet Pool with Struct Config ```csharp public sealed class Bullet { public Vector3 Position; public Vector3 Velocity; public float Damage; public float Lifetime; public void Reset() { Position = default; Velocity = default; Damage = 0; Lifetime = 0; } } public sealed class BulletManager { private readonly JObjectPool<Bullet> _pool = new( maxSize: 200, onReturn: static b => b.Reset()); public void Initialize() => _pool.Prewarm(100); public Bullet Fire(in Vector3 pos, in Vector3 dir, float speed, float damage) { var bullet = _pool.Rent(); bullet.Position = pos; bullet.Velocity = dir * speed; bullet.Damage = damage; return bullet; } public void Return(Bullet b) => _pool.Return(b); } ``` ### Enemy Spawner (Zero-GC State) ```csharp public sealed class Enemy : IPoolable { public float Health { get; set; } public Vector3 Position { get; set; } public event Action OnDeath; public void OnSpawn() { Health = 100f; } public void OnDespawn() { OnDeath = null; // Clear delegates to prevent leaks } } public sealed class EnemySpawner { private readonly JObjectPool<Enemy> _pool; public EnemySpawner(int maxSize = 50) { _pool = new( maxSize, onRent: static e => e.OnSpawn(), onReturn: static e => e.OnDespawn()); } public Enemy Spawn(in Vector3 position) { var enemy = _pool.Rent(); enemy.Position = position; return enemy; } public void Despawn(Enemy e) => _pool.Return(e); } ``` ### Temporary Collection (Zero-GC in Update) ```csharp // Use in hot paths to avoid List<T> allocations public void ProcessNearbyEnemies(in Vector3 center, float radius) { var list = JObjectPool.Shared<List<Enemy>>().Rent(); try { FindEnemiesNonAlloc(center, radius, list); foreach (var enemy in list) { ProcessEnemy(enemy); } } finally { list.Clear(); JObjectPool.Shared<List<Enemy>>().Return(list); } } ``` ### StringBuilder Pool (Zero-GC String Building) ```csharp public static string FormatDamage(float damage, string targetName) { var sb = JObjectPool.Shared<StringBuilder>().Rent(); try { sb.Append(targetName); sb.Append(" took "); sb.Append(damage.ToString("F1")); sb.Append(" damage"); return sb.ToString(); } finally { sb.Clear(); JObjectPool.Shared<StringBuilder>().Return(sb); } } ``` ## Best Practices 1. **Pre-allocate during loading** to prevent in-game allocation spikes 2. **Reset state on return** to prevent data leaks between reuses 3. **Set appropriate maxSize** based on expected concurrent usage 4. **Use shared pools** for simple objects without custom callbacks 5. **Monitor pool Count** to optimize sizing ## Troubleshooting ### Objects Not Reused - **Forgot to Return:** Always call `pool.Return(obj)` when done - **Pool at capacity:** Increase maxSize if concurrent usage exceeds limit - **Returning null:** Null values are silently ignored ### Stale Data / Memory Leaks - **Not resetting state:** Clear all fields in onReturn callback - **Event delegates:** Unsubscribe all events in onReturn to prevent leaks - **References to disposed objects:** Null out references in onReturn ### Performance Issues - **Not pre-warming:** Call `Prewarm()` during loading screens - **maxSize too low:** Causes allocations when pool empties - **maxSize too high:** Wastes memory ### Thread Safety - JObjectPool IS thread-safe (lock-free CAS) - Safe to Rent/Return from any thread - onRent/onReturn run on calling thread ## Common Mistakes - Returning null to pool (ignored, but wasteful) - Not clearing object state on return (causes bugs from stale data) - Forgetting to return objects (pool becomes ineffective) - Setting maxSize too low (causes frequent allocations) - Setting maxSize too high (wastes memory)