Add custom ObjectPoolProvider support for pooled registrations

.gitignore

@@ -109,7 +109,6 @@ publish/
 *.pubxml
 
 # NuGet Packages Directory
-## TODO: If you have NuGet Package Restore enabled, uncomment the next line
 packages/
 
 # Windows Azure Build Output
@@ -123,6 +122,8 @@ AppPackages/
 sql/
 *.Cache
 ClientBin/
+[Ss]tyle[Cc]op.*
+!stylecop.json
 ~$*
 *~
 *.dbmdl
@@ -132,6 +133,7 @@ node_modules/
 bower_components/
 wwwroot/
 project.lock.json
+*.Designer.cs
 
 # RIA/Silverlight projects
 Generated_Code/

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: "e72a3ca1632f0b11a07d171449fe447a7ff6795e"  # frozen: v0.48.0
+    rev: "c7c1c7640e610068e8e4754e9f1bf109bd987dc7"  # post-v0.48.0 with patches
     hooks:
       - id: markdownlint
         args:

.vscode/extensions.json

@@ -2,6 +2,7 @@
   "recommendations": [
     "davidanson.vscode-markdownlint",
     "editorconfig.editorconfig",
-    "ms-dotnettools.csharp"
+    "ms-dotnettools.csdevkit",
+    "travisillig.vscode-json-stable-stringify"
   ]
 }

.vscode/settings.json

@@ -3,5 +3,30 @@
     "autofac",
     "xunit"
   ],
-  "omnisharp.enableEditorConfigSupport": true
+  "coverage-gutters.coverageBaseDir": "artifacts/logs",
+  "coverage-gutters.coverageFileNames": [
+    "**/coverage.cobertura.xml"
+  ],
+  "dotnet.defaultSolution": "Autofac.Pooling.sln",
+  "dotnet.unitTestDebuggingOptions": {
+    "enableStepFiltering": false,
+    "justMyCode": false,
+    "requireExactSource": false,
+    "sourceLinkOptions": {
+      "*": {
+        "enabled": true
+      }
+    },
+    "suppressJITOptimizations": true,
+    "symbolOptions": {
+      "searchNuGetOrgSymbolServer": true
+    }
+  },
+  "explorer.fileNesting.enabled": true,
+  "explorer.fileNesting.patterns": {
+    "*.resx": "$(capture).*.resx, $(capture).designer.cs, $(capture).designer.vb"
+  },
+  "files.watcherExclude": {
+    "**/target": true
+  }
 }

.vscode/tasks.json

@@ -1,9 +1,37 @@
 {
+  "linux": {
+    "options": {
+      "shell": {
+        "args": [
+          "-NoProfile",
+          "-Command"
+        ],
+        "executable": "pwsh"
+      }
+    }
+  },
+  "osx": {
+    "options": {
+      "shell": {
+        "args": [
+          "-NoProfile",
+          "-Command"
+        ],
+        "executable": "/usr/local/bin/pwsh"
+      }
+    }
+  },
   "tasks": [
+    {
+      "command": "If (Test-Path ${workspaceFolder}/artifacts/logs) { Remove-Item ${workspaceFolder}/artifacts/logs -Recurse -Force }; New-Item -Path ${workspaceFolder}/artifacts/logs -ItemType Directory -Force | Out-Null",
+      "label": "create log directory",
+      "type": "shell"
+    },
     {
       "args": [
         "build",
-        "Autofac.Pooling.sln",
+        "${workspaceFolder}/Autofac.Pooling.sln",
+        "--tl:off",
         "/property:GenerateFullPaths=true",
         "/consoleloggerparameters:NoSummary"
       ],
@@ -13,12 +41,48 @@
         "kind": "build"
       },
       "label": "build",
-      "presentation": {
-        "reveal": "silent"
-      },
       "problemMatcher": "$msCompile",
       "type": "shell"
+    },
+    {
+      "args": [
+        "test",
+        "${workspaceFolder}/Autofac.Pooling.sln",
+        "/property:GenerateFullPaths=true",
+        "/consoleloggerparameters:NoSummary",
+        "--results-directory",
+        "artifacts/logs",
+        "--logger:trx",
+        "--collect:XPlat Code Coverage",
+        "--settings:build/Coverage.runsettings",
+        "--filter",
+        "FullyQualifiedName!~Bench"
+      ],
+      "command": "dotnet",
+      "dependsOn": [
+        "create log directory"
+      ],
+      "group": {
+        "isDefault": true,
+        "kind": "test"
+      },
+      "label": "test",
+      "problemMatcher": "$msCompile",
+      "type": "process"
     }
   ],
-  "version": "2.0.0"
+  "version": "2.0.0",
+  "windows": {
+    "options": {
+      "shell": {
+        "args": [
+          "-NoProfile",
+          "-ExecutionPolicy",
+          "Bypass",
+          "-Command"
+        ],
+        "executable": "pwsh.exe"
+      }
+    }
+  }
 }

LICENSE

@@ -1,4 +1,4 @@
-MIT License
+The MIT License (MIT)
 
 Copyright (c) 2020 Autofac Project
 

README.md

@@ -1,23 +1,19 @@
 # Autofac.Pooling
 
-[![Build status](https://github.com/autofac/Autofac.Pooling/actions/workflows/ci.yml/badge.svg?branch=develop)](https://github.com/autofac/Autofac.Pooling/actions/workflows/ci.yml) [![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/autofac/Autofac.Pooling)
+Support for pooled instance lifetime scopes in [Autofac](https://autofac.org) dependency injection. Autofac can help you implement a pool of components in your application without you having to write your own pooling implementation, and making these pooled components feel more natural in the world of DI.
 
-Support for pooled instance lifetime scopes in Autofac dependency injection.
-
-Autofac can help you implement a pool of components in your application without you having to write your
-own pooling implementation, and making these pooled components feel more natural in the world of DI.
+[![Build status](https://github.com/autofac/Autofac.Pooling/actions/workflows/main.yml/badge.svg)](https://github.com/autofac/Autofac.Pooling/actions/workflows/main.yml) [![codecov](https://codecov.io/gh/Autofac/Autofac.Pooling/branch/develop/graph/badge.svg)](https://codecov.io/gh/Autofac/Autofac.Pooling) [![NuGet](https://img.shields.io/nuget/v/Autofac.Pooling.svg)](https://nuget.org/packages/Autofac.Pooling)
 
 Please file issues and pull requests for this package in this repository rather than in the Autofac core repo.
 
 - [Documentation](https://autofac.readthedocs.io/advanced/pooled-instances.html)
 - [NuGet](https://www.nuget.org/packages/Autofac.Pooling)
 - [Contributing](https://autofac.readthedocs.io/en/latest/contributors.html)
+- [Open in Visual Studio Code](https://open.vscode.dev/autofac/Autofac.Pooling)
 
-## Getting Started
+## Quick Start
 
-Once you've added a reference to the `Autofac.Pooling` package, you can start using
-the new `PooledInstancePerLifetimeScope` and `PooledInstancePerMatchingLifetimeScope`
-methods:
+Once you've added a reference to the `Autofac.Pooling` package, you can start using the new `PooledInstancePerLifetimeScope` and `PooledInstancePerMatchingLifetimeScope` methods:
 
 ```csharp
 var builder = new ContainerBuilder();
@@ -52,7 +48,104 @@ using (var scope2 = container.BeginLifetimeScope())
 // end of the lifetime scope.
 ```
 
+## Custom Pool Providers
+
+By default, pooled instances are stored in a `DefaultObjectPool` sized from the policy's `MaximumRetained` value. If you need full control over *where* instances are stored and *when* they are evicted (for example, a cache-backed pool with an idle timeout), you can supply your own `Microsoft.Extensions.ObjectPool.ObjectPoolProvider`:
+
+```csharp
+var builder = new ContainerBuilder();
+
+// Register the backing cache in Autofac. Because it is registered here, the
+// container owns it and disposes it at shutdown, and it can be shared with the
+// rest of the application.
+builder.RegisterInstance(new MemoryCache(new MemoryCacheOptions()))
+        .As<IMemoryCache>();
+
+// Register the provider itself so Autofac constructs it and injects the cache.
+builder.RegisterType<CacheObjectPoolProvider>()
+        .SingleInstance();
+
+builder.RegisterType<MyCustomConnection>()
+        .As<ICustomConnection>()
+        // The provider factory receives the IComponentContext, so it can resolve
+        // the provider - and its dependencies - straight from the container.
+        .PooledInstancePerLifetimeScope(
+            ctx => ctx.Resolve<CacheObjectPoolProvider>());
+
+var container = builder.Build();
+```
+
+Autofac still owns *construction* of the pooled instances (they are resolved through the container, so dependency injection and the `IPooledComponent` / `IPooledRegistrationPolicy` callbacks all work as normal). The provider only controls storage and eviction. The provider's `Create<T>(IPooledObjectPolicy<T>)` method is the seam: Autofac hands in its own policy whose `Create()` resolves a fully-injected instance, so your pool delegates construction to it rather than new-ing up objects itself.
+
+A cache-backed provider that takes its cache from Autofac looks like this:
+
+```csharp
+public sealed class CacheObjectPoolProvider : ObjectPoolProvider
+{
+    private readonly IMemoryCache _cache;
+
+    // The cache is injected from Autofac rather than created here, so its
+    // lifetime is managed by the container and shared across every pool this
+    // provider creates.
+    public CacheObjectPoolProvider(IMemoryCache cache)
+    {
+        _cache = cache;
+    }
+
+    public override ObjectPool<T> Create<T>(IPooledObjectPolicy<T> policy)
+        => new CacheObjectPool<T>(_cache, policy);
+}
+
+public sealed class CacheObjectPool<T> : ObjectPool<T>
+    where T : class
+{
+    private readonly IMemoryCache _cache;
+    private readonly IPooledObjectPolicy<T> _policy;
+
+    public CacheObjectPool(IMemoryCache cache, IPooledObjectPolicy<T> policy)
+    {
+        _cache = cache;
+        _policy = policy;
+    }
+
+    public override T Get()
+        // Ask the cache for a stored instance; build a new one through Autofac on a miss.
+        => _cache.TryGetValue(typeof(T), out T? item) && item is not null
+            ? item
+            : _policy.Create();
+
+    public override void Return(T obj)
+    {
+        // The policy decides whether the instance is fit to be retained.
+        if (_policy.Return(obj))
+        {
+            // Dispose the instance when the cache eventually evicts it; the pool
+            // owns disposal of instances the cache drops.
+            var options = new MemoryCacheEntryOptions { SlidingExpiration = TimeSpan.FromMinutes(5) };
+            options.RegisterPostEvictionCallback((_, value, _, _) => (value as IDisposable)?.Dispose());
+            _cache.Set(typeof(T), obj, options);
+        }
+        else if (obj is IDisposable disposable)
+        {
+            // The pool owns disposal of instances it declines.
+            disposable.Dispose();
+        }
+    }
+}
+```
+
+The pool does not implement `IDisposable` because it does not own the cache — Autofac creates the `IMemoryCache`, so Autofac disposes it. The pool only takes responsibility for the pooled instances themselves, disposing them when the policy declines a return and when the cache evicts them.
+
+Things to know about custom providers:
+
+- The provider factory is invoked **once** per registration, when the pool is built, resolved from the pool-owning (root) scope. Because the factory gets an `IComponentContext`, the provider can be registered like any other component and resolved from the container, letting Autofac inject its dependencies (the `IMemoryCache` above). Registering the provider and cache as singletons shares one provider and cache across every type that uses them.
+- With a custom provider, `IPooledRegistrationPolicy.MaximumRetained` does **not** size the pool — the provider owns sizing and eviction. You can still supply a custom policy alongside the provider with the `PooledInstancePerLifetimeScope(policyFactory, providerFactory)` overload to control the `Get` / `Return` behavior.
+- The pool is **shared across all lifetime scopes and threads**, so your pool must be thread-safe.
+- **Disposal contract:**
+  - If the pool implements `IDisposable`, the container disposes it at container shutdown.
+  - Because `ObjectPool<T>.Return(T)` returns `void` (no kept/dropped signal) and there is no "permanently evicted" callback, **the custom pool is responsible for disposing instances it declines on `Return` or evicts asynchronously.** Autofac cannot see those instances.
+  - Instances that never entered the pool (because the policy chose not to call the pool) are disposed by normal lifetime scope disposal.
+
 ## Get Help
 
-**Need help with Autofac?** We have [a documentation site](https://autofac.readthedocs.io/) as well as [API documentation](https://autofac.org/apidoc/). We're ready to answer your questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/autofac)
-or check out the [discussion forum](https://groups.google.com/forum/#forum/autofac).
+**Need help with Autofac?** We have [a documentation site](https://autofac.readthedocs.io/) as well as [API documentation](https://autofac.org/apidoc/). We're ready to answer your questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/autofac) or check out the [discussion forum](https://groups.google.com/forum/#forum/autofac).

codecov.yml

@@ -1,3 +1,8 @@
 codecov:
   branch: develop
-  require_ci_to_pass: yes
+  require_ci_to_pass: true
+coverage:
+  status:
+    project:
+      default:
+        threshold: 1%