Auto circular object tracking (#31)

* Auto-tracking mapped objects when circular relationships are detected

* Changing TrackMappedObjects to MaintainIdentityIntegrity

* Adding DisableObjectTracking configuration option

* Test coverage for explicit disabling of mapped object caching

* Removing instance mappers from non-configured circular relationship tests

* Test coverage for mapping link relationships

Author: SteveWilkes

AgileMapper.PerformanceTester/ConcreteMappers/AgileMapper/AgileMapperComplexTypeMapper.cs

@@ -7,6 +7,7 @@ internal class AgileMapperComplexTypeMapper : ComplexTypeMapperBase
     {
         public override void Initialise()
         {
+            Mapper.WhenMapping.DisableObjectTracking();
         }
 
         protected override Foo Clone(Foo foo)

AgileMapper.UnitTests/Configuration/WhenConfiguringExceptionHandling.cs

@@ -161,7 +161,7 @@ public void ShouldRestrictACallbackBySourceAndTargetType()
                     .To<Person>()
                     .PassExceptionsTo(ctx => thrownException = ctx.Exception)
                     .And
-                    .TrackMappedObjects();
+                    .MaintainIdentityIntegrity();
 
                 mapper.After
                     .CreatingInstances

AgileMapper.UnitTests/WhenMappingCircularReferences.cs

@@ -76,7 +76,7 @@ public void ShouldCreateAComplexTypeArrayUsingRuntimeTypedElements()
         {
             using (var mapper = Mapper.CreateNew())
             {
-                mapper.WhenMapping.TrackMappedObjects();
+                mapper.WhenMapping.MaintainIdentityIntegrity();
 
                 var viewModel = new CustomerViewModel { Name = "Dave", AddressLine1 = "View model!" };
                 var source = new List<PersonViewModel> { viewModel, viewModel };

AgileMapper.UnitTests/WhenMappingToNewEnumerables.cs

@@ -315,8 +315,6 @@ public void ShouldShowObjectTracking()
         {
             using (var mapper = Mapper.CreateNew())
             {
-                mapper.WhenMapping.TrackMappedObjects();
-
                 string plan = mapper.GetPlanFor<Parent>().ToANew<Parent>();
 
                 plan.ShouldContain("pToPData.TryGet(sourceChild.EldestParent, out parent)");

AgileMapper.UnitTests/WhenViewingMappingPlans.cs

@@ -35,14 +35,30 @@ public interface IFullMappingSettings<TSource, TTarget> : IConditionalMappingCon
         IFullMappingSettings<TSource, TTarget> PassExceptionsTo(Action<IMappingExceptionData<TSource, TTarget>> callback);
 
         /// <summary>
-        /// Keep track of objects during a mapping from and to the source and target types being configured, in order 
-        /// to short-circuit circular relationships and ensure 1-to-1 relationships between source and mapped objects.
+        /// Ensure 1-to-1 relationships between source and mapped objects during a mapping from and to the source and 
+        /// target types being configured, by tracking and reusing mapped objects if they appear more than once in a 
+        /// source object tree. Mapped objects are automatically tracked in object trees with circular relationships - 
+        /// unless <see cref="DisableObjectTracking"/> is called - so configuring this option is not necessary just to 
+        /// map circular relationships.
         /// </summary>
         /// <returns>
-        /// An IFullMappingSettings{TSource, TTarget} with which to configure further settings for the source and
-        /// target types being configured.
+        /// An <see cref="IFullMappingSettings{TSource, TTarget}"/> with which to configure further settings for the source 
+        /// and target types being configured.
+        /// </returns>
+        IFullMappingSettings<TSource, TTarget> MaintainIdentityIntegrity();
+
+        /// <summary>
+        /// Disable tracking of objects during circular relationship mapping from and to the source and target types 
+        /// being configured. Mapped objects are tracked by default when mapping circular relationships to prevent stack 
+        /// overflows if two objects in a source object tree hold references to each other, and to ensure 1-to-1 relationships 
+        /// between source and mapped objects. If you are confident that each object in a source object tree appears 
+        /// only once, disabling object tracking will increase mapping performance.
+        /// </summary>
+        /// <returns>
+        /// An <see cref="IFullMappingSettings{TSource, TTarget}"/> with which to configure further settings for the source 
+        /// and target types being configured.
         /// </returns>
-        IFullMappingSettings<TSource, TTarget> TrackMappedObjects();
+        IFullMappingSettings<TSource, TTarget> DisableObjectTracking();
 
         /// <summary>
         /// Map null source collections to null instead of an empty collection, for the source and target types 

AgileMapper/Api/Configuration/IFullMappingSettings.cs

@@ -105,13 +105,27 @@ public interface IGlobalConfigSettings
         #endregion
 
         /// <summary>
-        /// Keep track of objects during mappings between all source and target types, in order to short-circuit 
-        /// circular relationships and ensure a 1-to-1 relationship between source and mapped objects.
+        /// Ensure 1-to-1 relationships between source and mapped objects by tracking and reusing mapped objects if 
+        /// they appear more than once in a source object tree. Mapped objects are automatically tracked in object 
+        /// trees with circular relationships - unless <see cref="DisableObjectTracking"/> is called - so configuring 
+        /// this option is not necessary just to map circular relationships.
         /// </summary>
         /// <returns>
         /// An <see cref="IGlobalConfigSettings"/> with which to globally configure other mapping aspects.
         /// </returns>
-        IGlobalConfigSettings TrackMappedObjects();
+        IGlobalConfigSettings MaintainIdentityIntegrity();
+
+        /// <summary>
+        /// Disable tracking of objects during circular relationship mapping between all source and target types. 
+        /// Mapped objects are tracked by default when mapping circular relationships to prevent stack overflows 
+        /// if two objects in a source object tree hold references to each other, and to ensure 1-to-1 relationships 
+        /// between source and mapped objects. If you are confident that each object in a source object tree appears 
+        /// only once, disabling object tracking will increase mapping performance.
+        /// </summary>
+        /// <returns>
+        /// An <see cref="IGlobalConfigSettings"/> with which to globally configure other mapping aspects.
+        /// </returns>
+        IGlobalConfigSettings DisableObjectTracking();
 
         /// <summary>
         /// Map null source collections to null instead of an empty collection, for all source and target types.

AgileMapper/Api/Configuration/IGlobalConfigSettings.cs

@@ -201,15 +201,33 @@ private IGlobalConfigSettings UseNamePatterns(IEnumerable<string> patterns)
         #endregion
 
         /// <summary>
-        /// Keep track of objects during mappings between all source and target types, in order to short-circuit 
-        /// circular relationships and ensure a 1-to-1 relationship between source and mapped objects.
+        /// Ensure 1-to-1 relationships between source and mapped objects by tracking and reusing mapped objects if 
+        /// they appear more than once in a source object tree. Mapped objects are automatically tracked in object 
+        /// trees with circular relationships - unless <see cref="DisableObjectTracking"/> is called - so configuring 
+        /// this option is not necessary when mapping circular relationships.
         /// </summary>
         /// <returns>
-        /// This <see cref="IGlobalConfigSettings"/> with which to globally configure other mapping aspects.
+        /// An <see cref="IGlobalConfigSettings"/> with which to globally configure other mapping aspects.
+        /// </returns>
+        public IGlobalConfigSettings MaintainIdentityIntegrity()
+        {
+            _mapperContext.UserConfigurations.Add(MappedObjectCachingSettings.CacheAll(_mapperContext));
+            return this;
+        }
+
+        /// <summary>
+        /// Disable tracking of objects during circular relationship mapping between all source and target types. 
+        /// Mapped objects are tracked by default when mapping circular relationships to prevent stack overflows 
+        /// if two objects in a source object tree hold references to each other, and to ensure 1-to-1 relationships 
+        /// between source and mapped objects. If you are confident that each object in a source object tree appears 
+        /// only once, disabling object tracking will increase mapping performance.
+        /// </summary>
+        /// <returns>
+        /// An <see cref="IGlobalConfigSettings"/> with which to globally configure other mapping aspects.
         /// </returns>
-        public IGlobalConfigSettings TrackMappedObjects()
+        public IGlobalConfigSettings DisableObjectTracking()
         {
-            _mapperContext.UserConfigurations.Add(ObjectTrackingMode.TrackAll(_mapperContext));
+            _mapperContext.UserConfigurations.Add(MappedObjectCachingSettings.CacheNone(_mapperContext));
             return this;
         }
 

AgileMapper/Api/Configuration/MappingConfigStartingPoint.cs

@@ -66,11 +66,15 @@ public IFullMappingSettings<TSource, TTarget> PassExceptionsTo(Action<IMappingEx
             return this;
         }
 
-        public IFullMappingSettings<TSource, TTarget> TrackMappedObjects()
+        public IFullMappingSettings<TSource, TTarget> MaintainIdentityIntegrity() => SetMappedObjectCaching(cache: true);
+
+        public IFullMappingSettings<TSource, TTarget> DisableObjectTracking() => SetMappedObjectCaching(cache: false);
+
+        private IFullMappingSettings<TSource, TTarget> SetMappedObjectCaching(bool cache)
         {
-            var trackingMode = new ObjectTrackingMode(ConfigInfo.ForTargetType<TTarget>());
+            var settings = new MappedObjectCachingSettings(ConfigInfo.ForTargetType<TTarget>(), cache);
 
-            ConfigInfo.MapperContext.UserConfigurations.Add(trackingMode);
+            ConfigInfo.MapperContext.UserConfigurations.Add(settings);
             return this;
         }
 

AgileMapper/Api/Configuration/MappingConfigurator.cs

@@ -0,0 +1,26 @@
+namespace AgileObjects.AgileMapper.Configuration
+{
+    internal class MappedObjectCachingSettings : UserConfiguredItemBase
+    {
+        public MappedObjectCachingSettings(MappingConfigInfo configInfo, bool cache)
+            : base(configInfo)
+        {
+            Cache = cache;
+        }
+
+        #region Factory Methods
+
+        public static MappedObjectCachingSettings CacheAll(MapperContext mapperContext)
+            => new MappedObjectCachingSettings(ForAllMappings(mapperContext), cache: true);
+
+        public static MappedObjectCachingSettings CacheNone(MapperContext mapperContext)
+            => new MappedObjectCachingSettings(ForAllMappings(mapperContext), cache: false);
+
+        private static MappingConfigInfo ForAllMappings(MapperContext mapperContext)
+            => MappingConfigInfo.AllRuleSetsSourceTypesAndTargetTypes(mapperContext);
+
+        #endregion
+
+        public bool Cache { get; }
+    }
+}