ResourcePool.cs

/*
 * Copyright 2017 Stanislav Muhametsin. All rights Reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied.
 *
 * See the License for the specific language governing permissions and
 * limitations under the License. 
 */
using ResourcePooling.Async.Abstractions;
using ResourcePooling.Async.Implementation;
using System;
using System.Collections.Generic;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using UtilPack;

namespace ResourcePooling.Async.Implementation
{
 /// <summary>
 /// This class implements the <see cref="AsyncResourcePoolObservable{TResource}"/> interface in such way that the resource is disposed of every time it is returned back to the pool.
 /// </summary>
 /// <typeparam name="TResource">The type of resource.</typeparam>
 /// <typeparam name="TResourceInstance">The type of instance holding the resource.</typeparam>
 /// <remarks>
 /// While this class is useful in simple scenarios, e.g. testing, the actual production environments most likely will want to use <see cref="CachingAsyncResourcePoolWithTimeout{TResource}"/> which is inherited from this class.
 /// </remarks>
 /// <seealso cref="CachingAsyncResourcePoolWithTimeout{TResource}"/>
 /// <seealso cref="CachingAsyncResourcePool{TResource, TResourceInstance}"/>
 internal class OneTimeUseAsyncResourcePool<TResource, TResourceInstance> : AsyncResourcePoolObservable<TResource>
 {

 /// <summary>
 /// Creates a new instance of <see cref="OneTimeUseAsyncResourcePool{TResource, TResourceInstance}"/>
 /// </summary>
 /// <param name="factory">The <see cref="AsyncResourceFactory{TResource, TParams}"/> to use for creation of new resources.</param>
 /// <param name="resourceExtractor">The callback to extract <see cref="AsyncResourceAcquireInfo{TResource}"/> from instances of <typeparamref name="TResourceInstance"/>.</param>
 /// <param name="instanceCreator">The callback to create a new instance of <typeparamref name="TResourceInstance"/> from existing <see cref="AsyncResourceAcquireInfo{TResource}"/>.</param>
 /// <exception cref="ArgumentNullException">If any of <paramref name="factory"/>, <paramref name="resourceExtractor"/>, or <paramref name="instanceCreator"/> is <c>null</c>.</exception>
 public OneTimeUseAsyncResourcePool(
 AsyncResourceFactory<TResource> factory,
 Func<TResourceInstance, AsyncResourceAcquireInfo<TResource>> resourceExtractor,
 Func<AsyncResourceAcquireInfo<TResource>, TResourceInstance> instanceCreator
 )
 {
 //this.FactoryParameters = factoryParameters;
 this.Factory = ArgumentValidator.ValidateNotNull( nameof( factory ), factory );
 this.ResourceExtractor = ArgumentValidator.ValidateNotNull( nameof( resourceExtractor ), resourceExtractor );
 this.InstanceCreator = ArgumentValidator.ValidateNotNull( nameof( instanceCreator ), instanceCreator );
 }

 /// <summary>
 /// Gets the <see cref="AsyncResourceFactory{TResource, TParams}"/> used to create new instances of resources.
 /// </summary>
 /// <value>The <see cref="AsyncResourceFactory{TResource, TParams}"/> used to create new instances of resources.</value>
 protected AsyncResourceFactory<TResource> Factory { get; }

 /// <summary>
 /// Gets the callback to extract <see cref="AsyncResourceAcquireInfo{TResource}"/> from instances of <typeparamref name="TResourceInstance"/>.
 /// </summary>
 /// <value>The callback to extract <see cref="AsyncResourceAcquireInfo{TResource}"/> from instances of <typeparamref name="TResourceInstance"/>.</value>
 protected Func<TResourceInstance, AsyncResourceAcquireInfo<TResource>> ResourceExtractor { get; }

 /// <summary>
 /// Gets the callback to create a new instance of <typeparamref name="TResourceInstance"/> from existing <see cref="AsyncResourceAcquireInfo{TResource}"/>.
 /// </summary>
 /// <value>The callback to create a new instance of <typeparamref name="TResourceInstance"/> from existing <see cref="AsyncResourceAcquireInfo{TResource}"/>.</value>
 protected Func<AsyncResourceAcquireInfo<TResource>, TResourceInstance> InstanceCreator { get; }

 /// <summary>
 /// Implements <see cref="ResourceFactoryInformation.ResetFactoryState"/> and calls the same method for this <see cref="Factory"/>.
 /// </summary>
 public void ResetFactoryState()
 {
 this.Factory.ResetFactoryState();
 }

 public AsyncResourceUsage<TResource> GetResourceUsage( CancellationToken token )
 {
 var instanceAcquired = 0;
 TResourceInstance instance = default;
 ResourceUsageInfo<TResource> usage = default;
 return new DefaultAsyncResourceUsage<TResource>(
 token,
 async () =>
 {
 instance = await this.AcquireResourceAsync( token );
 Interlocked.Exchange( ref instanceAcquired, 1 );
 usage = this.ResourceExtractor( instance ).GetResourceUsageForToken( token );
 return usage.Resource;
 },
 async () =>
 {
 try
 {
 usage?.Dispose();
 }
 finally
 {
 if ( instanceAcquired == 1 )
 {
 await ( this.DisposeResourceAsync( instance, token ) ?? TaskUtils.CompletedTask );
 }
 }
 }
 );
 }

 //public Task UseResourceAsync( Func<TResource, Task> user, CancellationToken token = default( CancellationToken ) )
 //{
 // // Avoid potentially allocating new instance of Task on every call to this method, and check for user and token cancellation first.
 // return user == null ? TaskUtils.CompletedTask : ( token.IsCancellationRequested ?
 // TaskUtils.FromCanceled( token ) :
 // this.DoUseResourceAsync( user, token )
 // );

 //}

 //private async Task DoUseResourceAsync( Func<TResource, Task> executer, CancellationToken token )
 //{
 // var instance = await this.AcquireResourceAsync( token );
 // try
 // {
 // using ( var usageInfo = this.ResourceExtractor( instance ).GetResourceUsageForToken( token ) )
 // {
 // await executer( usageInfo.Resource );
 // }
 // }
 // finally
 // {
 // await ( this.DisposeResourceAsync( instance, token ) ?? TaskUtils.CompletedTask );
 // }
 //}

 //public async ValueTask<ExplicitResourceAcquireInfo<TResource>> TakeResourceAsync( CancellationToken token )
 //{
 // var acquireResult = await this.AcquireResourceAsync( token );
 // return new ExplicitResourceAcquireInfoImpl<TResource, TResourceInstance>( acquireResult, this.ResourceExtractor( acquireResult ), token );
 //}

 //public async ValueTask<Boolean> ReturnResource( ExplicitResourceAcquireInfo<TResource> resourceInfo )
 //{
 // var retVal = false;
 // if ( resourceInfo != null )
 // {
 // if ( resourceInfo is ExplicitResourceAcquireInfoImpl<TResource, TResourceInstance> resource )
 // {
 // retVal = true;
 // resource.UsageInfo.DisposeSafely();
 // await this.DisposeResourceAsync( resource.InstanceInfo, resource.Token );
 // }
 // else
 // {
 // await ( resourceInfo.Resource as IAsyncDisposable ).DisposeAsyncSafely();
 // ( resourceInfo.Resource as IDisposable ).DisposeSafely();
 // }
 // }

 // return retVal;
 //}

 /// <summary>
 /// Implements <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.AfterResourceCreationEvent"/>.
 /// </summary>
 public event GenericEventHandler<AfterAsyncResourceCreationEventArgs<TResource>> AfterResourceCreationEvent;

 /// <summary>
 /// Implements <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.AfterResourceAcquiringEvent"/>.
 /// </summary>
 public event GenericEventHandler<AfterAsyncResourceAcquiringEventArgs<TResource>> AfterResourceAcquiringEvent;

 /// <summary>
 /// Implements <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceReturningEvent"/>.
 /// </summary>
 public event GenericEventHandler<BeforeAsyncResourceReturningEventArgs<TResource>> BeforeResourceReturningEvent;

 /// <summary>
 /// Implements <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceCloseEvent"/>.
 /// </summary>
 public event GenericEventHandler<BeforeAsyncResourceCloseEventArgs<TResource>> BeforeResourceCloseEvent;

 /// <summary>
 /// Helper property to get instance of <see cref="AfterResourceAcquiringEvent"/> for derived classes.
 /// </summary>
 /// <value>The instance of <see cref="AfterResourceAcquiringEvent"/> for derived classes.</value>
 protected GenericEventHandler<AfterAsyncResourceAcquiringEventArgs<TResource>> AfterResourceAcquiringEventInstance => this.AfterResourceAcquiringEvent;

 /// <summary>
 /// This method is called by <see cref="AsyncResourceUsage{TResource}.AwaitForResource"/> via callback provided by <see cref="GetResourceUsage"/> method.
 /// The implementation in this class always uses <see cref="AsyncResourceFactory{TResource}.CreateAcquireResourceContext(CancellationToken)"/> method of this <see cref="Factory"/>, but derived classes may override this method to cache previously used resources into a pool.
 /// </summary>
 /// <param name="token">The <see cref="CancellationToken"/> to use.</param>
 /// <returns>A task which will have instance of <typeparamref name="TResourceInstance"/> upon completion.</returns>
 protected virtual async ValueTask<TResourceInstance> AcquireResourceAsync( CancellationToken token )
 {
 var connAcquireInfo = await this.Factory.AcquireResourceAsync( token );
 var creationEvent = this.AfterResourceCreationEvent;
 var acquireEvent = this.AfterResourceAcquiringEvent;
 if ( creationEvent != null || acquireEvent != null )
 {
 using ( var usageInfo = connAcquireInfo.GetResourceUsageForToken( token ) )
 {
 await creationEvent.InvokeAndWaitForAwaitables( new DefaultAfterAsyncResourceCreationEventArgs<TResource>( usageInfo.Resource ) );
 await acquireEvent.InvokeAndWaitForAwaitables( new DefaultAfterAsyncResourceAcquiringEventArgs<TResource>( usageInfo.Resource ) );
 }
 }

 return this.InstanceCreator( connAcquireInfo );
 }

 /// <summary>
 /// This method is called by <see cref="IAsyncDisposable.DisposeAsync"/> of the <see cref="AsyncResourceUsage{TResource}"/> returned by <see cref="GetResourceUsage"/>.
 /// </summary>
 /// <param name="resource">The resource that is being returned to pool.</param>
 /// <param name="token">The <see cref="CancellationToken"/>.</param>
 /// <returns>Task which is completed when disposing the resource is completed.</returns>
 /// <remarks>
 /// This method simply calls <see cref="PerformDisposeResourceAsync(TResourceInstance, CancellationToken, ResourceDisposeKind)"/> and gives <c>true</c> to both boolean arguments.
 /// </remarks>
 protected virtual async Task DisposeResourceAsync( TResourceInstance resource, CancellationToken token )
 {
 await this.PerformDisposeResourceAsync( resource, token, ResourceDisposeKind.ReturnAndDispose );
 }

 /// <summary>
 /// This method will take care of invoking the <see cref="BeforeResourceReturningEvent"/> and <see cref="BeforeResourceCloseEvent"/> before actually disposing the given resource.
 /// </summary>
 /// <param name="resource">The resource instance.</param>
 /// <param name="token">The <see cref="CancellationToken"/>.</param>
 /// <param name="disposeKind">How to dispose the <paramref name="resource"/>.</param>
 /// <returns>A task which completes after all necessary event invocation and resource dispose code is done.</returns>
 /// <seealso cref="ResourceDisposeKind"/>
 protected async Task PerformDisposeResourceAsync(
 TResourceInstance resource,
 CancellationToken token,
 ResourceDisposeKind disposeKind
 )
 {
 var returningEvent = this.BeforeResourceReturningEvent;
 var closingEvent = this.BeforeResourceCloseEvent;
 var isResourceClosed = disposeKind.IsResourceClosed();
 var isResourceReturned = disposeKind.IsResourceReturned();
 if ( ( returningEvent != null && isResourceReturned ) || ( closingEvent != null && isResourceClosed ) )
 {
 using ( var usageInfo = this.ResourceExtractor( resource ).GetResourceUsageForToken( token ) )
 {
 if ( isResourceReturned )
 {
 await returningEvent.InvokeAndWaitForAwaitables( new DefaultBeforeAsyncResourceReturningEventArgs<TResource>( usageInfo.Resource ) );
 }

 if ( isResourceClosed )
 {
 await closingEvent.InvokeAndWaitForAwaitables( new DefaultBeforeAsyncResourceCloseEventArgs<TResource>( usageInfo.Resource ) );
 }
 }
 }

 if ( isResourceClosed )
 {
 await this.ResourceExtractor( resource ).DisposeAsyncSafely();
 }
 }



 }

 /// <summary>
 /// This enumeration controls how <see cref="OneTimeUseAsyncResourcePool{TResource, TResourceInstance}.PerformDisposeResourceAsync(TResourceInstance, CancellationToken, ResourceDisposeKind)"/> method will behave.
 /// </summary>
 public enum ResourceDisposeKind
 {
 /// <summary>
 /// The resource is closed, but closing happens right after returning the resource to the pool.
 /// Both the <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceReturningEvent"/> and <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceCloseEvent"/> will be invoked, in that order.
 /// Finally, the resource will be asynchronously disposed of.
 /// </summary>
 ReturnAndDispose,

 /// <summary>
 /// The resource is returned to the pool, but not closed.
 /// Only <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceReturningEvent"/> will be invoked, and the resource will not be disposed.
 /// </summary>
 OnlyReturn,

 /// <summary>
 /// The resource is closed, and not returned to the pool.
 /// Only <see cref="ResourcePoolObservation{TResource, TCreationArgs, TAcquiringArgs, TReturningArgs, TCloseArgs}.BeforeResourceCloseEvent"/> will be invoked, and resource will be then disposed.
 /// </summary>
 OnlyDispose
 }

 /// <summary>
 /// This class extends <see cref="OneTimeUseAsyncResourcePool{TResource, TResourceInstance}"/> and implements rudimentary pooling for resource instances.
 /// The pool is never cleared by this class though, since this class does not define any logic for how to perform clean-up operation for the pool.
 /// The <see cref="CachingAsyncResourcePoolWithTimeout{TResource}"/> extends this class and defines exactly that.
 /// </summary>
 /// <typeparam name="TResource">The type of resource.</typeparam>
 /// <typeparam name="TCachedResource">The type of instance holding the resource. This will be the type for <see cref="LocklessInstancePoolForClassesNoHeapAllocations{TInstance}"/> object used to pool resource instances.</typeparam>
 /// <remarks>
 /// This class is not very useful by itself - instead it provides some common implementation for pooling resource instances.
 /// End-users will find <see cref="CachingAsyncResourcePoolWithTimeout{TResource}"/> much more useful.
 /// </remarks>
 /// <seealso cref="CachingAsyncResourcePoolWithTimeout{TResource}"/>
 internal class CachingAsyncResourcePool<TResource, TCachedResource> : OneTimeUseAsyncResourcePool<TResource, TCachedResource>, IAsyncDisposableWithToken, IDisposable
 where TCachedResource : class, InstanceWithNextInfo<TCachedResource>
 {
 private const Int32 NOT_DISPOSED = 0;
 private const Int32 DISPOSED = 1;

 private Int32 _disposed;

 private readonly TakeFromInstancePoolDelegate<TCachedResource> _takeFromPool;
 private readonly ReturnToInstancePoolDelegate<TCachedResource> _returnToPool;

 ///// <summary>
 ///// Creates a new instance of <see cref="CachingAsyncResourcePool{TResource, TResourceInstance, TResourceCreationParams}"/> with given parameters.
 ///// </summary>
 ///// <param name="factory">The <see cref="AsyncResourceFactory{TResource, TParams}"/> to use for creation of new resources.</param>
 ///// <param name="factoryParameters">The parameters to passe to <see cref="AsyncResourceFactory{TResource, TParams}"/> when creating new instances of resources.</param>
 ///// <param name="resourceExtractor">The callback to extract <see cref="AsyncResourceAcquireInfo{TResource}"/> from instances of <typeparamref name="TCachedResource"/>.</param>
 ///// <param name="instanceCreator">The callback to create a new instance of <typeparamref name="TCachedResource"/> from existing <see cref="AsyncResourceAcquireInfo{TResource}"/>.</param>
 ///// <exception cref="ArgumentNullException">If any of <paramref name="factory"/>, <paramref name="resourceExtractor"/>, or <paramref name="instanceCreator"/> is <c>null</c>.</exception>
 public CachingAsyncResourcePool(
 AsyncResourceFactory<TResource> factory,
 Func<TCachedResource, AsyncResourceAcquireInfo<TResource>> resourceExtractor,
 Func<AsyncResourceAcquireInfo<TResource>, TCachedResource> instanceCreator,
 TakeFromInstancePoolDelegate<TCachedResource> takeFromPool,
 ReturnToInstancePoolDelegate<TCachedResource> returnToPool
 ) : base( factory, resourceExtractor, instanceCreator )
 {
 this.Pool = new LocklessInstancePoolForClassesNoHeapAllocations<TCachedResource>();
 this._takeFromPool = takeFromPool ?? ( ( p, t ) => new ValueTask<TCachedResource>( p.TakeInstance() ) );
 this._returnToPool = returnToPool ?? ( ( p, t, i ) => { p?.ReturnInstance( i ); return new ValueTask<Boolean>( p != null && i != null ); } );
 }

 /// <summary>
 /// Gets the actual instance-caching pool used by this <see cref="CachingAsyncResourcePool{TResource, TResourceInstance}"/>.
 /// </summary>
 /// <value>The actual instance-caching pool used by this <see cref="CachingAsyncResourcePool{TResource, TResourceInstance}"/>.</value>
 /// <seealso cref="LocklessInstancePoolForClassesNoHeapAllocations{TInstance}"/>
 protected LocklessInstancePoolForClassesNoHeapAllocations<TCachedResource> Pool { get; }

 /// <summary>
 /// Implements <see cref="IAsyncDisposableWithToken.DisposeAsync"/> method to empty the <see cref="Pool"/> from all resources and dispose them asynchronously.
 /// </summary>
 /// <param name="token">The cancellation token to use.</param>
 /// <returns>A task which will be completed when all resource instances in <see cref="Pool"/> are asynchronously disposed.</returns>
 public virtual async Task DisposeAsync( CancellationToken token )
 {
 if ( Interlocked.CompareExchange( ref this._disposed, DISPOSED, NOT_DISPOSED ) == NOT_DISPOSED )
 {
 TCachedResource conn;
 while ( ( conn = this.Pool.TakeInstance() ) != null )
 {
 try
 {
 await base.PerformDisposeResourceAsync( conn, token, ResourceDisposeKind.OnlyDispose );
 }
 catch
 {
 // Most likely we will not enter here, but better be safe than sorry.
 }
 }
 }
 }

 public Task DisposeAsync() => this.DisposeAsync( default );

 /// <summary>
 /// Implements <see cref="IDisposable.Dispose"/> to empty the <see cref="Pool"/> from all resources and dispose them synchronously.
 /// </summary>
 /// <remarks>
 /// The asynchronous disposing via <see cref="DisposeAsync(CancellationToken)"/> method is preferable, but this method can be used when there is no time to wait potentially long time for all resources to become disposed asynchronously.
 /// </remarks>
 public void Dispose()
 {
 if ( Interlocked.CompareExchange( ref this._disposed, DISPOSED, NOT_DISPOSED ) == NOT_DISPOSED )
 {
 this.DisposeAllInPool();
 }
 }

 private void DisposeAllInPool()
 {
 TCachedResource conn;
 while ( ( conn = this.Pool.TakeInstance() ) != null )
 {
 this.ResourceExtractor( conn ).DisposeSafely();
 }
 }

 /// <summary>
 /// This property checks whether this <see cref="CachingAsyncResourcePool{TResource, TResourceInstance}"/> is disposed, or being in process of disposing.
 /// </summary>
 /// <value><c>true</c> if this <see cref="CachingAsyncResourcePool{TResource, TResourceInstance}"/> is disposed, or being in process of disposing; <c>false</c> otherwise.</value>
 public Boolean Disposed => this._disposed != NOT_DISPOSED;

 /// <summary>
 /// This method overrides <see cref="OneTimeUseAsyncResourcePool{TResource, TResourceInstance}.AcquireResourceAsync(CancellationToken)"/> to implement logic where instead of always using <see cref="AsyncResourceFactory{TResource, TParams}"/>, the existing resource instance may be acquired from this <see cref="Pool"/>.
 /// </summary>
 /// <param name="token">The <see cref="CancellationToken"/> to use when acquiring new resource from <see cref="AsyncResourceFactory{TResource, TParams}"/>.</param>
 /// <returns>A task which completes when the resource has been acquired.</returns>
 protected override async ValueTask<TCachedResource> AcquireResourceAsync( CancellationToken token )
 {
 if ( this.Disposed )
 {
 throw new ObjectDisposedException( "This pool is already disposed or being disposed of." );
 }

 var retVal = await this._takeFromPool( this.Pool, token );
 if ( retVal == null )
 {
 // Create resource and await for events
 retVal = await base.AcquireResourceAsync( token );
 }
 else
 {
 // Just await for acquire event
 var evt = this.AfterResourceAcquiringEventInstance;
 if ( evt != null )
 {
 using ( var usageInfo = this.ResourceExtractor( retVal ).GetResourceUsageForToken( token ) )
 {
 await evt.InvokeAndWaitForAwaitables( new DefaultAfterAsyncResourceAcquiringEventArgs<TResource>( usageInfo.Resource ) );
 }
 }
 }

 return retVal;
 }

 /// <summary>
 /// This method overrides <see cref="OneTimeUseAsyncResourcePool{TResource, TResourceInstance}.DisposeResourceAsync(TResourceInstance, CancellationToken)"/> in order to return the resource to this <see cref="Pool"/>, if it is returnable back to the pool as specified by <see cref="AbstractResourceAcquireInfo.IsResourceReturnableToPool"/>.
 /// </summary>
 /// <param name="instance">The resource instance to dispose or to return to the <see cref="Pool"/>.</param>
 /// <param name="token">The <see cref="CancellationToken"/> to use when disposing asynchronously.</param>
 /// <returns>A task which completes once all events have been invoked and resource either disposed of or returned to this <see cref="Pool"/>.</returns>
 protected override async Task DisposeResourceAsync( TCachedResource instance, CancellationToken token )
 {
 await this.PerformDisposeResourceAsync( instance, token, ResourceDisposeKind.OnlyReturn );
 var info = this.ResourceExtractor( instance );

 if ( !this.Disposed && info.IsResourceReturnableToPool )
 {
 await this._returnToPool( this.Pool, token, instance );
 // We might've disposed or started to dispose asynchronously after returning to pool in such way that racing condition may occur.
 if ( this.Disposed )
 {
 this.DisposeAllInPool();
 }
 }
 else
 {
 await this._returnToPool( null, token, instance );
 await info.DisposeAsyncSafely( token );
 }
 }
 }

 /// <summary>
 /// This class extends <see cref="CachingAsyncResourcePool{TResource, TCachedResource}"/> to add information when the resource was returned to the pool, in order to be able to clean it up later using <see cref="CleanUpAsync(TimeSpan, CancellationToken)"/> method.
 /// </summary>
 /// <typeparam name="TResource">The type of resource exposed to public.</typeparam>
 internal class CachingAsyncResourcePoolWithTimeout<TResource> : CachingAsyncResourcePool<TResource, InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>>>, AsyncResourcePoolObservable<TResource, TimeSpan>
 {
 ///// <summary>
 ///// Creates a new instance of <see cref="CachingAsyncResourcePoolWithTimeout{TResource, TResourceCreationParams}"/> with given parameters.
 ///// </summary>
 ///// <param name="factory">The <see cref="AsyncResourceFactory{TResource, TParams}"/> to use when needed to create new instances of resource.</param>
 ///// <param name="factoryParameters">The parameters to pass when using <see cref="AsyncResourceFactory{TResource, TParams}.AcquireResourceAsync(TParams, CancellationToken)"/> of <paramref name="factory"/>.</param>
 ///// <exception cref="ArgumentNullException">If <paramref name="factory"/> is <c>null</c>.</exception>
 public CachingAsyncResourcePoolWithTimeout(
 AsyncResourceFactory<TResource> factory,
 TakeFromInstancePoolDelegate<InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>>> takeFromPool,
 ReturnToInstancePoolDelegate<InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>>> returnToPool
 )
 : base( factory, /*factoryParameters,*/ instance => instance.Instance, resource => new InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>>( resource ), takeFromPool, returnToPool )
 {
 }

 /// <summary>
 /// This method overrides <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.DisposeResourceAsync(TCachedResource, CancellationToken)"/> to register return time of the resource.
 /// </summary>
 /// <param name="instance">The resource instance to dispose or to return to the <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/>.</param>
 /// <param name="token">The <see cref="CancellationToken"/> to use when disposing asynchronously.</param>
 /// <returns>A task which completes once all events have been invoked and resource either disposed of or returned to this <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/>.</returns>
 protected override async Task DisposeResourceAsync( InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>> instance, CancellationToken token )
 {
 instance.JustBeforePuttingBackToPool();
 await base.DisposeResourceAsync( instance, token );
 }

 /// <summary>
 /// This method implements <see cref="AsyncResourcePoolCleanUp{TCleanUpParameter}.CleanUpAsync(TCleanUpParameter, CancellationToken)"/> with <see cref="TimeSpan"/> as clean-up parameter.
 /// The <paramref name="maxResourceIdleTime"/> will serve as limit: this method will dispose all resource instances which have been idle in the <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/> for longer than the limit.
 /// During this method execution, this <see cref="CachingAsyncResourcePoolWithTimeout{TResource}"/> will continue to be usable as normally.
 /// </summary>
 /// <param name="maxResourceIdleTime">The maximum idle time for resource in the <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/> for it to be returned back to the pool. If idle time is longer than (operator <c>&gt;</c>) this parameter, then the resource will be disposed.</param>
 /// <param name="token">The <see cref="CancellationToken"/> to use when disposing.</param>
 /// <returns>A task which will be complete when all of the resource instances of <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/> have been checked and resource eligible for clean-up will be disposed of.</returns>
 public async Task CleanUpAsync( TimeSpan maxResourceIdleTime, CancellationToken token )
 {
 InstanceHolderWithTimestamp<AsyncResourceAcquireInfo<TResource>> instance;
 var tasks = new List<Task>();
 while ( ( instance = this.Pool.TakeInstance() ) != null )
 {
 if ( DateTime.UtcNow - instance.TimeOfReturningBackToPool > maxResourceIdleTime )
 {
 tasks.Add( this.PerformDisposeResourceAsync( instance, token, ResourceDisposeKind.OnlyDispose ) );
 }
 else
 {
 this.Pool.ReturnInstance( instance );
 }
 }

 await
#if NET40
 TaskEx
#else
 Task
#endif
 .WhenAll( tasks );
 }
 }

 /// <summary>
 /// This class is used by <see cref="CachingAsyncResourcePoolWithTimeout{TResource}"/> to capture the time when resource instance was returned to the <see cref="CachingAsyncResourcePool{TResource, TCachedResource}.Pool"/>.
 /// </summary>
 /// <typeparam name="TResource">The type of resource.</typeparam>
 public sealed class InstanceHolderWithTimestamp<TResource> : InstanceWithNextInfo<InstanceHolderWithTimestamp<TResource>>
 {
 private InstanceHolderWithTimestamp<TResource> _next;
 private Object _lastChanged;

 /// <summary>
 /// Creates a new instance of <see cref="InstanceHolderWithTimestamp{TResource}"/>
 /// </summary>
 /// <param name="instance"></param>
 public InstanceHolderWithTimestamp( TResource instance )
 {
 this.Instance = instance;
 }

 /// <summary>
 /// Gets the resource instance.
 /// </summary>
 /// <value>The resoruce instance.</value>
 public TResource Instance { get; }

 /// <summary>
 /// Gets or sets the next <see cref="InstanceHolderWithTimestamp{TResource}"/> for this pool.
 /// </summary>
 /// <value>The next <see cref="InstanceHolderWithTimestamp{TResource}"/> for this pool.</value>
 public InstanceHolderWithTimestamp<TResource> Next
 {
 get
 {
 return this._next;
 }
 set
 {
 Interlocked.Exchange( ref this._next, value );
 }
 }

 /// <summary>
 /// Gets the <see cref="DateTime"/> when this instance was returned to pool.
 /// </summary>
 /// <value>The <see cref="DateTime"/> when this instance was returned to pool.</value>
 /// <exception cref="NullReferenceException">If this <see cref="InstanceHolderWithTimestamp{TResource}"/> has never been put back to the pool before.</exception>
 public DateTime TimeOfReturningBackToPool
 {
 get
 {
 return (DateTime) this._lastChanged;
 }
 }

 /// <summary>
 /// Marks this <see cref="InstanceHolderWithTimestamp{TResource}"/> as being returned to pool, thus updating the value of <see cref="TimeOfReturningBackToPool"/>.
 /// </summary>
 public void JustBeforePuttingBackToPool()
 {
 Interlocked.Exchange( ref this._lastChanged, DateTime.UtcNow );
 }
 }

 //internal sealed class ExplicitResourceAcquireInfoImpl<TResource, TInstance> : ExplicitResourceAcquireInfo<TResource>
 //{
 // public ExplicitResourceAcquireInfoImpl(
 // TInstance instance,
 // AsyncResourceAcquireInfo<TResource> acquireInfo,
 // CancellationToken token
 // )
 // {
 // this.Token = token;
 // this.InstanceInfo = instance;
 // this.UsageInfo = acquireInfo.GetResourceUsageForToken( token );
 // }


 // public TResource Resource => this.UsageInfo.Resource;

 // internal ResourceUsageInfo<TResource> UsageInfo { get; }

 // internal TInstance InstanceInfo { get; }

 // internal CancellationToken Token { get; }
 //}

 //internal class AsyncResourcePoolWrapper<TResource> : AsyncResourcePoolObservable<TResource>
 //{
 // private readonly AsyncResourcePoolObservable<TResource> _actual;

 // public AsyncResourcePoolWrapper( AsyncResourcePoolObservable<TResource> actual )
 // {
 // this._actual = ArgumentValidator.ValidateNotNull( nameof( actual ), actual );
 // }

 // public event GenericEventHandler<AfterAsyncResourceCreationEventArgs<TResource>> AfterResourceCreationEvent
 // {
 // add
 // {
 // this._actual.AfterResourceCreationEvent += value;
 // }

 // remove
 // {
 // this._actual.AfterResourceCreationEvent -= value;
 // }
 // }

 // public event GenericEventHandler<AfterAsyncResourceAcquiringEventArgs<TResource>> AfterResourceAcquiringEvent
 // {
 // add
 // {
 // this._actual.AfterResourceAcquiringEvent += value;
 // }

 // remove
 // {
 // this._actual.AfterResourceAcquiringEvent -= value;
 // }
 // }

 // public event GenericEventHandler<BeforeAsyncResourceReturningEventArgs<TResource>> BeforeResourceReturningEvent
 // {
 // add
 // {
 // this._actual.BeforeResourceReturningEvent += value;
 // }

 // remove
 // {
 // this._actual.BeforeResourceReturningEvent -= value;
 // }
 // }

 // public event GenericEventHandler<BeforeAsyncResourceCloseEventArgs<TResource>> BeforeResourceCloseEvent
 // {
 // add
 // {
 // this._actual.BeforeResourceCloseEvent += value;
 // }

 // remove
 // {
 // this._actual.BeforeResourceCloseEvent -= value;
 // }
 // }

 // public void ResetFactoryState()
 // {
 // this._actual.ResetFactoryState();
 // }

 // public Task UseResourceAsync( Func<TResource, Task> user, CancellationToken token )
 // {
 // return this._actual.UseResourceAsync( user, token );
 // }
 //}

 //internal sealed class CleanUpAsyncResourcePoolWrapper<TResource, TCleanUpParameter> : AsyncResourcePoolWrapper<TResource>, AsyncResourcePoolObservable<TResource, TCleanUpParameter>
 //{
 // private readonly AsyncResourcePoolObservable<TResource, TCleanUpParameter> _actual;

 // public CleanUpAsyncResourcePoolWrapper(
 // AsyncResourcePoolObservable<TResource, TCleanUpParameter> actual
 // ) : base( actual )
 // {
 // this._actual = actual;
 // }

 // public Task CleanUpAsync( TCleanUpParameter cleanupParameter, CancellationToken token )
 // {
 // return this._actual.CleanUpAsync( cleanupParameter, token );
 // }

 // public void Dispose()
 // {
 // this._actual.Dispose();
 // }
 //}
}



/// <summary>
/// This class contains extension methods for types defined in this assembly.
/// </summary>
public static partial class E_ResourcePooling
{
 /// <summary>
 /// Returns <c>true</c> if this <see cref="ResourceDisposeKind"/> is the kind which indicates returning resource to pool.
 /// </summary>
 /// <param name="kind">This <see cref="ResourceDisposeKind"/>.</param>
 /// <returns><c>true</c> if this <see cref="ResourceDisposeKind"/> is either <see cref="ResourceDisposeKind.ReturnAndDispose"/> or <see cref="ResourceDisposeKind.OnlyReturn"/>; <c>false</c> otherwise.</returns>
 public static Boolean IsResourceReturned( this ResourceDisposeKind kind )
 {
 return kind == ResourceDisposeKind.ReturnAndDispose || kind == ResourceDisposeKind.OnlyReturn;
 }

 /// <summary>
 /// Returns <c>true</c> if this <see cref="ResourceDisposeKind"/> is the kind which indicates disposal of resource.
 /// </summary>
 /// <param name="kind">This <see cref="ResourceDisposeKind"/>.</param>
 /// <returns><c>true</c> if this <see cref="ResourceDisposeKind"/> is either <see cref="ResourceDisposeKind.ReturnAndDispose"/> or <see cref="ResourceDisposeKind.OnlyDispose"/>; <c>false</c> otherwise.</returns>
 public static Boolean IsResourceClosed( this ResourceDisposeKind kind )
 {
 return kind == ResourceDisposeKind.ReturnAndDispose || kind == ResourceDisposeKind.OnlyDispose;
 }
}