Lagoon 2.0.1

dotnet add package Lagoon --version 2.0.1
                    
NuGet\Install-Package Lagoon -Version 2.0.1
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Lagoon" Version="2.0.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Lagoon" Version="2.0.1" />
                    
Directory.Packages.props
<PackageReference Include="Lagoon" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Lagoon --version 2.0.1
                    
#r "nuget: Lagoon, 2.0.1"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Lagoon@2.0.1
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Lagoon&version=2.0.1
                    
Install as a Cake Addin
#tool nuget:?package=Lagoon&version=2.0.1
                    
Install as a Cake Tool

Lagoon

pipeline status

Nuget

Lagoon is an object pool for .NET. It pools objects that are expensive to initialize. Think database connections or network connections in general.

Installation

Lagoon targets net10.0. Install via NuGet:

dotnet add package Lagoon

If you want the IServiceCollection integration, also install:

dotnet add package Lagoon.DependencyInjection

Usage

Objects you want to pool must implement IDisposable, and you provide an IObjectPoolFactory<TObject> that knows how to create and (optionally) activate them:

TObject must be an interface, not a concrete class. GetObjectAsync doesn't hand you the raw object -- it wraps it in a Castle DynamicProxy interface proxy so that calling Dispose() on it can be intercepted and redirected back into the pool instead of actually destroying the object (see Architecture below). Castle's CreateInterfaceProxyWithTarget requires an interface to proxy against; passing a concrete class as TObject compiles fine (the only constraint is class, IDisposable) but fails at runtime with ArgumentException: Specified type is not an interface the first time the pool tries to create an object -- pool through an interface your class implements instead.

public interface IObjectPoolFactory<TObject>
    where TObject : class, IDisposable
{
    TObject Create();
    Task ActivateAsync(TObject obj, CancellationToken token = default);
}
using Lagoon;

var factory = new MyFactory(); // implements IObjectPoolFactory<MyObject>

var pool = new DefaultObjectPool<MyObject>(factory);

using (var obj = await pool.GetObjectAsync())
{
    // do something with the object
} // obj is not actually disposed here -- Dispose() returns it to the pool instead

pool.Dispose(); // disposes the pool, and every object still in it

Get an object with pool.GetObjectAsync(). Disposing the returned object doesn't dispose the underlying instance -- it returns it to the pool for reuse. pool.Dispose() disposes the pool itself along with every object currently sitting idle in it. Disposing the pool while objects are still checked out throws an InvalidOperationException, so make sure everything you've borrowed has been returned first.

Options

Pass an ObjectPoolOptions to DefaultObjectPool<TObject> to control pool sizing and timeouts:

var options = new ObjectPoolOptions
{
    MinObjects = 3,                                // pool tries to keep at least this many objects on hand
    MaxObjects = 10,                                // GetObjectAsync blocks (up to AcquisitionTimeout) once this many are checked out
    SweepFrequency = TimeSpan.FromSeconds(10),       // how often the pool grows/prunes toward MinObjects
    AcquisitionTimeout = TimeSpan.FromSeconds(30),   // how long GetObjectAsync waits before throwing PoolExhaustedException
};

var pool = new DefaultObjectPool<MyObject>(factory, options);

Activation and passivation

You can also pass predicates that gate whether your factory's ActivateAsync runs when an object is created, and whether an idle object actually gets disposed when the pool prunes or shuts down:

var pool = new DefaultObjectPool<MyObject>(
    factory,
    options,
    objectActivator: obj => obj.NeedsActivation,
    objectPassivator: obj => obj.CanBeDisposed);

Both default to always returning true if omitted.

Dependency injection

Lagoon.DependencyInjection adds an AddObjectPool<TObject> extension for IServiceCollection. Register your IObjectPoolFactory<TObject> implementation separately -- AddObjectPool resolves it from the container:

using Lagoon.DependencyInjection;

services.AddSingleton<IObjectPoolFactory<MyObject>, MyFactory>();
services.AddObjectPool<MyObject>(options =>
{
    options.MaxObjects = 20;
});

This registers IObjectPool<TObject> as a singleton (via TryAddSingleton, so it won't override a registration you've already made).

Architecture

  • IObjectPoolFactory<TObject> -- you implement this. It creates objects and, optionally, activates them.
  • DefaultObjectPool<TObject> -- the pool implementation. Idle objects live in a ConcurrentStack; checked-out objects are tracked in a ConcurrentDictionary until returned.
  • PooledObjectWrapper<TObject> -- what GetObjectAsync actually hands you is a Castle DynamicProxy interface proxy wrapping your object (which is why TObject must be an interface -- see the note under Usage). Calling Dispose() on it is intercepted and redirected to return the object to the pool rather than disposing it; only the pool itself disposes the underlying instance, when pruning or during pool.Dispose().
  • Background maintenance -- two timers run for the lifetime of the pool, on the interval set by SweepFrequency: one prunes idle objects back toward MinObjects (respecting objectPassivator), the other grows the pool back up toward MinObjects when it's below that count.
  • Exhaustion -- if the pool is at MaxObjects and all objects are checked out, GetObjectAsync waits for one to be returned (woken via a signal rather than polling), up to AcquisitionTimeout, after which it throws PoolExhaustedException. Errors thrown by your factory during creation or activation are wrapped in PoolException.

Notes on Usage

  • The objects to be pooled must implement IDisposable, and TObject must be an interface (not a concrete class) -- see the note under Usage.
  • The pool itself is meant to be used throughout your application.

This repo is a companion to a blog series about object pool patterns.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Lagoon:

Package Downloads
Lagoon.DependencyInjection

Dependency injection extensions for Lagoon.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.1 151 8/3/2026
2.0.1-beta.20260803083449 73 8/3/2026
2.0.1-beta.20260803081923 78 8/3/2026
2.0.1-beta.20260803073200 81 8/3/2026
2.0.0 137 7/18/2026
2.0.0-beta.20260723214620 75 7/23/2026
2.0.0-beta.20260718094140 76 7/18/2026
2.0.0-beta.20260718083259 69 7/18/2026
1.2.0-beta.20260718081558 73 7/18/2026
1.1.0 383 9/30/2023
1.1.0-beta.20211202023705 293 12/2/2021
1.1.0-beta.20211202023153 290 12/2/2021
1.1.0-beta.20201111113301 374 11/11/2020
1.0.0 862 10/29/2020
1.0.0-beta.20201029045223 407 10/29/2020
1.0.0-beta.20201029043813 433 10/29/2020
1.0.0-beta.20201029043604 419 10/29/2020
1.0.0-beta.20201029043113 436 10/29/2020
1.0.0-beta.20201028051918 415 10/28/2020