VersionStamp.cs

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information.

using System;
using System.Diagnostics;
using System.Threading;
using Roslyn.Utilities;

namespace Microsoft.CodeAnalysis
{
    /// <summary>
    /// VersionStamp should be only used to compare versions returned by same API.
    /// </summary>
    public readonly struct VersionStamp : IEquatable<VersionStamp>, IObjectWritable
    {
        public static VersionStamp Default => default;

        private const int GlobalVersionMarker = -1;
        private const int InitialGlobalVersion = 10000;

        /// <summary>
        /// global counter to avoid collision within same session. 
        /// it starts with a big initial number just for a clarity in debugging
        /// </summary>
        private static int s_globalVersion = InitialGlobalVersion;

        /// <summary>
        /// time stamp
        /// </summary>
        private readonly DateTime _utcLastModified;

        /// <summary>
        /// indicate whether there was a collision on same item
        /// </summary>
        private readonly int _localIncrement;

        /// <summary>
        /// unique version in same session
        /// </summary>
        private readonly int _globalIncrement;

        private VersionStamp(DateTime utcLastModified)
            : this(utcLastModified, 0)
        {
        }

        private VersionStamp(DateTime utcLastModified, int localIncrement)
            : this(utcLastModified, localIncrement, GetNextGlobalVersion())
        {
        }

        private VersionStamp(DateTime utcLastModified, int localIncrement, int globalIncrement)
        {
            if (utcLastModified != default && utcLastModified.Kind != DateTimeKind.Utc)
            {
                throw new ArgumentException(WorkspacesResources.DateTimeKind_must_be_Utc, nameof(utcLastModified));
            }

            _utcLastModified = utcLastModified;
            _localIncrement = localIncrement;
            _globalIncrement = globalIncrement;
        }

        /// <summary>
        /// Creates a new instance of a VersionStamp.
        /// </summary>
        public static VersionStamp Create()
            => new(DateTime.UtcNow);

        /// <summary>
        /// Creates a new instance of a version stamp based on the specified DateTime.
        /// </summary>
        public static VersionStamp Create(DateTime utcTimeLastModified)
            => new(utcTimeLastModified);

        /// <summary>
        /// compare two different versions and return either one of the versions if there is no collision, otherwise, create a new version
        /// that can be used later to compare versions between different items
        /// </summary>
        public VersionStamp GetNewerVersion(VersionStamp version)
        {
            // * NOTE *
            // in current design/implementation, there are 4 possible ways for a version to be created.
            //
            // 1. created from a file stamp (most likely by starting a new session). "increment" will have 0 as value
            // 2. created by modifying existing item (text changes, project changes etc).
            //    "increment" will have either 0 or previous increment + 1 if there was a collision.
            // 3. created from deserialization (probably by using persistent service).
            // 4. created by accumulating versions of multiple items.
            //
            // and this method is the one that is responsible for #4 case.

            if (_utcLastModified > version._utcLastModified)
            {
                return this;
            }

            if (_utcLastModified == version._utcLastModified)
            {
                var thisGlobalVersion = GetGlobalVersion(this);
                var thatGlobalVersion = GetGlobalVersion(version);

                if (thisGlobalVersion == thatGlobalVersion)
                {
                    // given versions are same one
                    return this;
                }

                // mark it as global version
                // global version can't be moved to newer version.
                return new VersionStamp(_utcLastModified, (thisGlobalVersion > thatGlobalVersion) ? thisGlobalVersion : thatGlobalVersion, GlobalVersionMarker);
            }

            return version;
        }

        /// <summary>
        /// Gets a new VersionStamp that is guaranteed to be newer than its base one
        /// this should only be used for same item to move it to newer version
        /// </summary>
        public VersionStamp GetNewerVersion()
        {
            // global version can't be moved to newer version
            Debug.Assert(_globalIncrement != GlobalVersionMarker);

            var now = DateTime.UtcNow;
            var incr = (now == _utcLastModified) ? _localIncrement + 1 : 0;

            return new VersionStamp(now, incr);
        }

        /// <summary>
        /// Returns the serialized text form of the VersionStamp.
        /// </summary>
        public override string ToString()
        {
            // 'o' is the roundtrip format that captures the most detail.
            return _utcLastModified.ToString("o") + "-" + _globalIncrement + "-" + _localIncrement;
        }

        public override int GetHashCode()
            => Hash.Combine(_utcLastModified.GetHashCode(), _localIncrement);

        public override bool Equals(object? obj)
        {
            if (obj is VersionStamp v)
            {
                return this.Equals(v);
            }

            return false;
        }

        public bool Equals(VersionStamp version)
        {
            if (_utcLastModified == version._utcLastModified)
            {
                return GetGlobalVersion(this) == GetGlobalVersion(version);
            }

            return false;
        }

        public static bool operator ==(VersionStamp left, VersionStamp right)
            => left.Equals(right);

        public static bool operator !=(VersionStamp left, VersionStamp right)
            => !left.Equals(right);

        /// <summary>
        /// Check whether given persisted version is re-usable. Used by VS for Mac
        /// </summary>
        internal static bool CanReusePersistedVersion(VersionStamp baseVersion, VersionStamp persistedVersion)
        {
            if (baseVersion == persistedVersion)
            {
                return true;
            }

            // there was a collision, we can't use these
            if (baseVersion._localIncrement != 0 || persistedVersion._localIncrement != 0)
            {
                return false;
            }

            return baseVersion._utcLastModified == persistedVersion._utcLastModified;
        }

        bool IObjectWritable.ShouldReuseInSerialization => true;

        void IObjectWritable.WriteTo(ObjectWriter writer)
            => WriteTo(writer);

        internal void WriteTo(ObjectWriter writer)
        {
            writer.WriteInt64(_utcLastModified.ToBinary());
            writer.WriteInt32(_localIncrement);
            writer.WriteInt32(_globalIncrement);
        }

        internal static VersionStamp ReadFrom(ObjectReader reader)
        {
            var raw = reader.ReadInt64();
            var localIncrement = reader.ReadInt32();
            var globalIncrement = reader.ReadInt32();

            return new VersionStamp(DateTime.FromBinary(raw), localIncrement, globalIncrement);
        }

        private static int GetGlobalVersion(VersionStamp version)
        {
            // global increment < 0 means it is a global version which has its global increment in local increment
            return version._globalIncrement >= 0 ? version._globalIncrement : version._localIncrement;
        }

        private static int GetNextGlobalVersion()
        {
            // REVIEW: not sure what is best way to wrap it when it overflows. should I just throw or don't care.
            // with 50ms (typing) as an interval for a new version, it gives more than 1 year before int32 to overflow.
            // with 5ms as an interval, it gives more than 120 days before it overflows.
            // since global version is only for per VS session, I think we don't need to worry about overflow.
            // or we could use Int64 which will give more than a million years turn around even on 1ms interval.

            // this will let versions to be compared safely between multiple items
            // without worrying about collision within same session
            var globalVersion = Interlocked.Increment(ref VersionStamp.s_globalVersion);

            return globalVersion;
        }

        internal TestAccessor GetTestAccessor()
            => new(this);

        internal readonly struct TestAccessor
        {
            private readonly VersionStamp _versionStamp;

            public TestAccessor(in VersionStamp versionStamp)
                => _versionStamp = versionStamp;

            /// <summary>
            /// True if this VersionStamp is newer than the specified one.
            /// </summary>
            internal bool IsNewerThan(in VersionStamp version)
            {
                if (_versionStamp._utcLastModified > version._utcLastModified)
                {
                    return true;
                }

                if (_versionStamp._utcLastModified == version._utcLastModified)
                {
                    return GetGlobalVersion(_versionStamp) > GetGlobalVersion(version);
                }

                return false;
            }
        }
    }
}