Merge pull request #24118 from dotnet-maestro-bot/merge/master-to-release/3.0

[automated] Merge branch 'master' => 'release/3.0'

Author: wtgodbe

BuildToolsVersion.txt

@@ -1 +1 @@
-3.0.0-preview4-03906-01
+3.0.0-preview4-03913-01

Documentation/Profiling/Profiler Loading.md

@@ -16,7 +16,7 @@ If any of these environment variable are present, we skip the registry look up a
 
 A couple things to note about this:
 - If you specify `CORECLR_PROFILER_PATH` _and_ register your profiler, then `CORECLR_PROFILER_PATH` always wins.  Even if `CORECLR_PROFILER_PATH` points to an invalid path, we will still use `CORECLR_PROFILER_PATH`, and just fail to load your profiler.
-- `CORECLR_R_PROFILER` is _always required_.  If you specify `CORECLR_PROFILER_PATH`, we skip the registry look up. We still need to know your profiler's CLSID, so we can pass it to your class factory's CreateInstance call.
+- `CORECLR_PROFILER` is _always required_.  If you specify `CORECLR_PROFILER_PATH`, we skip the registry look up. We still need to know your profiler's CLSID, so we can pass it to your class factory's CreateInstance call.
 
 
 ## Through the registry (Windows Only)

Documentation/Profiling/davbr-blog-archive/samples/PlugInToYourProfiler.cpp

@@ -50,7 +50,7 @@ Visual Studio Express is not supported.
 
 ## CMake
 
-The CoreCLR repo build has been validated using CMake 3.9.3.
+The CoreCLR repo build has been validated using CMake 3.9.3. When using Visual Studio 2019 at least version 3.14.1 is required. 
 
 - Install [CMake](http://www.cmake.org/download) for Windows.
 - Add its location (e.g. C:\Program Files (x86)\CMake\bin) to the PATH environment variable.  
@@ -60,7 +60,7 @@ The CoreCLR repo build has been validated using CMake 3.9.3.
 
 ## Python
 
-Python is used in the build system. We are currently using python 2.7.9, although
+Python is used in the build system. We are currently using Python 2.7.9, although
 any recent (2.4+) version of Python should work, including Python 3.
 - Install [Python](https://www.python.org/downloads/) for Windows.
 - Add its location (e.g. C:\Python*\) to the PATH environment variable.  

Documentation/Profiling/davbr-blog-archive/samples/sigparse.cpp

@@ -3,6 +3,8 @@
 ### Posts that take a high-level overview of releases
 
 - [Corestart 2.0: What's new for performance in .NET Core 2.0](https://www.ageofascent.com/2017/11/05/perfromance-dotnet-core-2-corestart-conference/)
+- [Performance improvements in .NET Core 2.0](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-core/)
+- [Performance improvements in .NET Core 2.1](https://devblogs.microsoft.com/dotnet/performance-improvements-in-net-core-2-1/)
 
 
 ### Posts that take a high-level look at the entire source:

Documentation/building/windows-instructions.md

@@ -51,6 +51,7 @@ namespace System.Reflection
     {
         public static Assembly Load(string assemblyString);
         public static Assembly Load(AssemblyName assemblyRef);
+        public static Assembly LoadWithPartialName (string partialName);
     }
 }
 ```
@@ -65,8 +66,18 @@ namespace System
         public static Type GetType(string typeName);
     }
 }
+
+namespace System.Reflection
+{
+    public abstract partial class Assembly : ICustomAttributeProvider, ISerializable
+    {
+        public Type GetType(string typeName, bool throwOnError, bool ignoreCase);
+        public Type GetType(string typeName, bool throwOnError);
+        public Type GetType(string typeName);
+    }
+}
 ```
-#### Unamiguous APIs related to affected APIs
+#### Normally unamiguous APIs related to affected APIs
 ```C#
 namespace System
 {
@@ -78,9 +89,9 @@ namespace System
     }
 }
 ```
-In this case, `assemblyResolver` functionally specifies the explicit mechanism to load. This indicates the current assembly's `AssmblyLoadContext` is not being used. If the `assemblyResolver` is only serving as a first or last chance resolver, then these would also be in the set of affected APIs.
-#### Should be affected APIs
-Issue https://github.com/dotnet/coreclr/issues/22213, discusses scenarios in which various flavors of the API `GetType()` is not functioning correctly. As part of the analysis and fix of that issue, the set of affected APIs may increase.
+In this case, `assemblyResolver` functionally specifies the explicit mechanism to load.
+
+If the `assemblyResolver` is `null`, assembly loads for these occur when `typeName` includes a assembly-qualified type reference.
 ### Root cause analysis
 In .NET Framework, plugin isolation was provided by creating multiple `AppDomain` instances.  .NET Core dropped support for multiple `AppDomain` instances. Instead we introduced `AssemblyLoadContext`.
 
@@ -112,10 +123,10 @@ namespace System.Runtime.Loader
 {
     public partial class AssemblyLoadContext
     {
-        private static readonly AsyncLocal<AssemblyLoadContext> asyncLocalActiveContext = new AsyncLocal<AssemblyLoadContext>(null);
+        private static readonly AsyncLocal<AssemblyLoadContext> _asyncLocalActiveContext;
         public static AssemblyLoadContext CurrentContextualReflectionContext
         {
-            get { return _asyncLocalCurrentContextualReflectionContext.Value; }
+            get { return _asyncLocalCurrentContextualReflectionContext?.Value; }
         }
     }
 }
@@ -203,7 +214,7 @@ namespace System.Runtime.Loader
 {
     public partial class AssemblyLoadContext
     {
-        public static AssemblyLoadContext CurrentContextualReflectionContext { get { return _asyncLocalCurrentContextualReflectionContext.Value; }}
+        public static AssemblyLoadContext CurrentContextualReflectionContext { get { return _asyncLocalCurrentContextualReflectionContext?.Value; }}
 
         public ContextualReflectionScope EnterContextualReflection();
 
@@ -218,62 +229,93 @@ namespace System.Runtime.Loader
 ```
 ## Design doc
 
-Mostly TBD.
-
-### Performance Consideration
-#### Avoiding native / managed transitions
+### Affected runtime native calls
 
-My natural inclination would be to replace most native calls taking a `StackCrawlMark` with callS taking the `CurrentContextualReflectionContext`. When `CurrentContextualReflectionContext` is `null`, resolve the `StackCrawlMark` first, passing the result as the inferred context.
+The affected runtime native calls correspond to the runtime's mechanism to load an assembly, and to get a type. Each affected native call is passed a managed reference to the CurrentContextualReflectionContext.  This prevents GC holes, while running the native code. The `CurrentContextualReflectionContext` acts as the mechanism for resolving assembly names to assemblies.
 
-However this may require mutiple native/managed transitions. Performance considerations may require Native calls which currently take a `StackCrawlMark` will need to be modified to also take `CurrentContextualReflectionContext`.
+### Unloadability
 
-### Hypothetical Advanced/Problematic use cases
+`CurrentContextualReflectionContext` will hold an `AssemblyLoadContext` reference. This will prevent the context from being unloaded while it could be used. As an `AsyncLocal<AssemblyLoadContext>`, the setting will propagate to child threads and asynchronous tasks.
+After a thread or asynchronous task completes, the `AsyncLocal<AssemblyLoadContext>` will eventually be cleared, this will unblock the `AssemblyLoadContext` unload. The timing of this unload depends on the ThreadPool implementation.
 
-One could imagine complicated scenarios in which we need to handle ALCs on event callback boundaries. These are expected to be rare. The following are representative patterns that demonstrate the possibility to be support these more complicated usages.
+### ContextualReflectionScope
 
-#### An incoming event handler into an AssemblyLoadContext
 ```C#
-void OnEvent()
+/// <summary>Opaque disposable struct used to restore CurrentContextualReflectionContext</summary>
+/// <remarks>
+/// This is an implmentation detail of the AssemblyLoadContext.EnterContextualReflection APIs.
+/// It is a struct, to avoid heap allocation.
+/// It is required to be public to avoid boxing.
+/// <see cref="System.Runtime.Loader.AssemblyLoadContext.EnterContextualReflection"/>
+/// </remarks>
+[EditorBrowsable(EditorBrowsableState.Never)]
+public struct ContextualReflectionScope : IDisposable
 {
-  using (alc.Activate())
-  {
-    ...
-  }
-}
-```
-#### An incoming event handler into a collectible AssemblyLoadContext
-```C#
-class WeakAssemblyLoadContextEventHandler
-{
-  WeakReference<AssemblyLoadContext> weakAlc;
+    private readonly AssemblyLoadContext _activated;
+    private readonly AssemblyLoadContext _predecessor;
+    private readonly bool _initialized;
 
-  void OnEvent()
-  {
-    AssemblyLoadContext alc;
-    if(weakAlc.TryGetTarget(out alc))
+    internal ContextualReflectionScope(AssemblyLoadContext activating)
     {
-      using (alc.Activate())
-      {
-        ...
-      }
+        _predecessor = AssemblyLoadContext.CurrentContextualReflectionContext;
+        AssemblyLoadContext.SetCurrentContextualReflectionContext(activating);
+        _activated = activating;
+        _initialized = true;
+    }
+
+    public void Dispose()
+    {
+        if (_initialized)
+        {
+            // Do not clear initialized. Always restore the _predecessor in Dispose()
+            // _initialized = false;
+            AssemblyLoadContext.SetCurrentContextualReflectionContext(_predecessor);
+        }
     }
-  }
 }
 ```
-#### A outgoing callback
+
+`_initialized` is included to prevent useful default construction. It prevents the `default(ContextualReflectionScope).Dispose()` case.
+
+`_predecessor` represents the previous value of `CurrentContextualReflectionContext`. It is used by `Dispose()` to restore the previous state.
+
+`_activated` is included as a potential aid to debugging. It serves no other useful purpose.
+
+This struct is implemented as a readonly struct. No state is modified after construction. This means `Dispose()` can be called multiple times. This means `using` blocks will always restore the previous `CurrentContextualReflectionContext` as exiting.
+
+### Unusual usage patterns
+
+There are some unusual usage patterns which are not recommended, but not prohibited. They all have reasonable behaviors.
+
+* Clear but never restore the CurrentContextualReflectionContext
+```C#
+myAssemblyLoadContext.EnterContextualReflection(null);
+```
+
+* Set but never clear the CurrentContextualReflectionContext
 ```C#
-using (AssemblyLoadContext.Activate(null))
-{
-  Callback();
-}
+myAssemblyLoadContext.EnterContextualReflection();
 ```
-#### An outgoing event handler
+
+* Manual dispose
 ```C#
-void OnEvent()
+myAssemblyLoadContext.EnterContextualReflection();
+
+scope.Dispose();
+```
+
+* Multiple dispose
+```C#
+ContextualReflectionScope scope = myAssemblyLoadContext.EnterContextualReflection();
+
+scope.Dispose(); // Will restore the context as set during `EnterContextualReflection()`
+scope.Dispose(); // Will restore the context as set during `EnterContextualReflection()`  (again)
+```
+
+* Early dispose
+```C#
+using (ContextualReflectionScope scope = myAssemblyLoadContext.EnterContextualReflection())
 {
-  using (AssemblyLoadContext.Activate(null))
-  {
-    ...
-  }
-}
+    scope.Dispose(); // Will restore the context as set during `EnterContextualReflection()`
+} // `using` will restore the context as set during `EnterContextualReflection()` (again)
 ```

Documentation/deep-dive-blog-posts.md

@@ -350,13 +350,13 @@ public static class ConfigKnobsDoc
         "## Environment/Registry Configuration Knobs\n";
 
     public static string ClrConfigSectionInfo =
-        "This table was machine-generated using `clr-configuration-knobs.csx` script from repository commit [GIT_SHORT_HASH](https://github.com/dotnet/coreclr/commit/GIT_LONG_HASH) on DATE_CREATED. It might be out of date. To generate latest documentation run `{dotnet} csi clr-configuration-knobs.csx` from this file directory.\n";
+        "This table was machine-generated using `clr-configuration-knobs.csx` script from repository commit [GIT_SHORT_HASH](https://github.com/dotnet/coreclr/commit/GIT_LONG_HASH) on DATE_CREATED. It might be out of date. To generate latest documentation run `dotnet-script clr-configuration-knobs.csx` from this file directory.\n";
 
     public static string ClrConfigSectionUsage =
         "When using these configurations from environment variables, the variables need to have the `COMPlus_` prefix in their names. e.g. To set DumpJittedMethods to 1, add the environment variable `COMPlus_DumpJittedMethods=1`.\n\nSee also [Setting configuration variables](../building/viewing-jit-dumps.md#setting-configuration-variables) for more information.\n";
 
     public static string ClrConfigTableHeader =
-        "\nName | Description | Type | Class | Default Value | Flags \n" +
+        "\nName | Description | Type | Class | Default Value | Flags\n" +
         "-----|-------------|------|-------|---------------|-------\n";
 
     public static string PalConfigurationKnobs =
@@ -421,10 +421,10 @@ public static class ConfigKnobsDoc
                 foreach (string key in catKnobs.Keys)
                 {
                     var knob = catKnobs[key];
-                    writer.Write($"`{knob.Name}` | {knob.Description} | `{knob.Type}` | ");
-                    writer.Write(knob.Class.Length > 0 ? $"`{knob.Class}` | " : " | ");
-                    writer.Write(knob.DefaultValue.Length > 0 ? $"`{knob.DefaultValue}` | " : " | ");
-                    writer.WriteLine($"{ knob.Flags}");
+                    writer.Write($"`{knob.Name}` | {knob.Description} | `{knob.Type}` |");
+                    writer.Write(knob.Class.Length > 0 ? $" `{knob.Class}` |" : " |");
+                    writer.Write(knob.DefaultValue.Length > 0 ? $" `{knob.DefaultValue}` |" : " |");
+                    writer.WriteLine(knob.Flags.Length > 0 ? $" {knob.Flags}" : string.Empty);
                     count++;
                 }