// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

using System;
using System.Runtime.CompilerServices;

namespace Microsoft.AspNetCore.Http.Features
{
    /// <summary>
    /// A reference to a collection of features.
    /// </summary>
    /// <typeparam name="TCache">The type of the feature.</typeparam>
    public struct FeatureReferences<TCache>
    {
        /// <summary>
        /// Initializes a new instance of <see cref="FeatureReferences{TCache}"/>.
        /// </summary>
        /// <param name="collection">The <see cref="IFeatureCollection"/>.</param>
        public FeatureReferences(IFeatureCollection collection)
        {
            Collection = collection;
            Cache = default;
            Revision = collection.Revision;
        }

        /// <summary>
        /// Initializes the <see cref="FeatureReferences{TCache}"/>.
        /// </summary>
        /// <param name="collection">The <see cref="IFeatureCollection"/> to initialize with.</param>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public void Initalize(IFeatureCollection collection)
        {
            Revision = collection.Revision;
            Collection = collection;
        }

        /// <summary>
        /// Initializes the <see cref="FeatureReferences{TCache}"/>.
        /// </summary>
        /// <param name="collection">The <see cref="IFeatureCollection"/> to initialize with.</param>
        /// <param name="revision">The version of the <see cref="IFeatureCollection"/>.</param>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public void Initalize(IFeatureCollection collection, int revision)
        {
            Revision = revision;
            Collection = collection;
        }

        /// <summary>
        /// Gets the <see cref="IFeatureCollection"/>.
        /// </summary>
        public IFeatureCollection Collection { get; private set; }

        /// <summary>
        /// Gets the revision number.
        /// </summary>
        public int Revision { get; private set; }

        // cache is a public field because the code calling Fetch must
        // be able to pass ref values that "dot through" the TCache struct memory,
        // if it was a Property then that getter would return a copy of the memory
        // preventing the use of "ref"
        /// <summary>
        /// This API is part of ASP.NET Core's infrastructure and should not be referenced by application code.
        /// </summary>
        public TCache? Cache;

        // Careful with modifications to the Fetch method; it is carefully constructed for inlining
        // See: https://github.com/aspnet/HttpAbstractions/pull/704
        // This method is 59 IL bytes and at inline call depth 3 from accessing a property.
        // This combination is enough for the jit to consider it an "unprofitable inline"
        // Aggressively inlining it causes the entire call chain to dissolve:
        //
        // This means this call graph:
        //
        // HttpResponse.Headers -> Response.HttpResponseFeature -> Fetch -> Fetch      -> Revision
        //                                                               -> Collection -> Collection
        //                                                                             -> Collection.Revision
        // Has 6 calls eliminated and becomes just:                                    -> UpdateCached
        //
        // HttpResponse.Headers -> Collection.Revision
        //                      -> UpdateCached (not called on fast path)
        //
        // As this is inlined at the callsite we want to keep the method small, so it only detects
        // if a reset or update is required and all the reset and update logic is pushed to UpdateCached.
        //
        // Generally Fetch is called at a ratio > x4 of UpdateCached so this is a large gain

        /// <summary>
        /// This API is part of ASP.NET Core's infrastructure and should not be referenced by application code.
        /// </summary>
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
        public TFeature? Fetch<TFeature, TState>(
            ref TFeature? cached,
            TState state,
            Func<TState, TFeature?> factory) where TFeature : class?
        {
            var flush = false;
            var revision = Collection?.Revision ?? ContextDisposed();
            if (Revision != revision)
            {
                // Clear cached value to force call to UpdateCached
                cached = null!;
                // Collection changed, clear whole feature cache
                flush = true;
            }

            return cached ?? UpdateCached(ref cached!, state, factory, revision, flush);
        }

        // Update and cache clearing logic, when the fast-path in Fetch isn't applicable
        private TFeature? UpdateCached<TFeature, TState>(ref TFeature? cached, TState state, Func<TState, TFeature?> factory, int revision, bool flush) where TFeature : class?
        {
            if (flush)
            {
                // Collection detected as changed, clear cache
                Cache = default;
            }

            cached = Collection.Get<TFeature>();
            if (cached == null)
            {
                // Item not in collection, create it with factory
                cached = factory(state);
                // Add item to IFeatureCollection
                Collection.Set(cached);
                // Revision changed by .Set, update revision to new value
                Revision = Collection.Revision;
            }
            else if (flush)
            {
                // Cache was cleared, but item retrieved from current Collection for version
                // so use passed in revision rather than making another virtual call
                Revision = revision;
            }

            return cached;
        }

        /// <summary>
        /// This API is part of ASP.NET Core's infrastructure and should not be referenced by application code.
        /// </summary>
        public TFeature? Fetch<TFeature>(ref TFeature? cached, Func<IFeatureCollection, TFeature?> factory)
            where TFeature : class? => Fetch(ref cached, Collection, factory);

        private static int ContextDisposed()
        {
            ThrowContextDisposed();
            return 0;
        }

        private static void ThrowContextDisposed()
        {
            throw new ObjectDisposedException(nameof(Collection), nameof(IFeatureCollection) + " has been disposed.");
        }
    }
}
