From cc8ed0015859ca222f986c9c2eceaffefbb3194c Mon Sep 17 00:00:00 2001 From: Elinor Fung Date: Sat, 9 Oct 2021 09:33:14 -0700 Subject: [PATCH] Updates to DllImportGenerator docs (#60211) --- .../DllImportGenerator/Compatibility.md | 8 ++-- .../DllImportGenerator/RuntimeConsumption.md | 43 ------------------- 2 files changed, 3 insertions(+), 48 deletions(-) delete mode 100644 docs/design/libraries/DllImportGenerator/RuntimeConsumption.md diff --git a/docs/design/libraries/DllImportGenerator/Compatibility.md b/docs/design/libraries/DllImportGenerator/Compatibility.md index 3a6ab0e6c94d5..2790eff6e8943 100644 --- a/docs/design/libraries/DllImportGenerator/Compatibility.md +++ b/docs/design/libraries/DllImportGenerator/Compatibility.md @@ -47,7 +47,7 @@ When converting from native to managed, the built-in system would throw a [`Mars In the built-in system, marshalling a `string` contains an optimization for parameters passed by value to allocate on the stack (instead of through [`AllocCoTaskMem`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.marshal.alloccotaskmem)) if the string is below a certain length (MAX_PATH). For UTF-16, this optimization was also applied for parameters passed by read-only reference. The generated marshalling code will include this optimization for read-only reference parameters for non-UTF-16 as well. -When marshalling as [ANSI](https://docs.microsoft.com/windows/win32/intl/code-pages) on Windows (using `CharSet.Ansi`, `CharSet.Auto`, or `UnmanagedType.LPStr`): +When marshalling as [ANSI](https://docs.microsoft.com/windows/win32/intl/code-pages) on Windows (using `CharSet.Ansi` or `UnmanagedType.LPStr`): - Best-fit mapping will be disabled and no exception will be thrown for unmappable characters. In the built-in system, this behaviour was configured through [`DllImportAttribute.BestFitMapping`] and [`DllImportAttribute.ThrowOnUnmappableChar`]. The generated marshalling code will have the equivalent behaviour of `BestFitMapping=false` and `ThrowOnUnmappableChar=false`. - No optimization for stack allocation will be performed. Marshalling will always allocate through `AllocCoTaskMem`. @@ -65,13 +65,11 @@ Specifying array-specific marshalling members on the `MarshalAsAttribute` such a Only single-dimensional arrays are supported for source generated marshalling. -Jagged arrays (arrays of arrays) are technically unsupported as was the case in the built-in marshalling system, but currently are not explicitly blocked by the source generator since they are not blocked at an architectural level, which was the case in the built-in system. - In the source-generated marshalling, arrays will be allocated on the stack (instead of through [`AllocCoTaskMem`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.marshal.alloccotaskmem)) if they are passed by value or by read-only reference if they contain at most 256 bytes of data. The built-in system does not support this optimization for arrays. ### `in` keyword -For some types - blittable or Unicode `char` - passed by read-only reference via the [`in` keyword](https://docs.microsoft.com/dotnet/csharp/language-reference/keywords/in-parameter-modifier), the built-in system simply pins the parameter. The generated marshalling code does the same. A consequence of this behaviour is that any modifications made by the invoked function will be reflected in the caller. It is left to the user to avoid the situation in which `in` is used for a parameter that will actually be modified by the invoked function. +For some types - blittable or Unicode `char` - passed by read-only reference via the [`in` keyword](https://docs.microsoft.com/dotnet/csharp/language-reference/keywords/in-parameter-modifier), the built-in system simply pins the parameter. The generated marshalling code does the same, such that there is no behavioural difference. A consequence of this behaviour is that any modifications made by the invoked function will be reflected in the caller. It is left to the user to avoid the situation in which `in` is used for a parameter that will actually be modified by the invoked function. ### `LCIDConversion` support @@ -92,6 +90,6 @@ Unlike the built-in system, the source generator does not support marshalling fo - [`HandleRef`](https://docs.microsoft.com/dotnet/api/system.runtime.interopservices.handleref) - [`StringBuilder`](https://docs.microsoft.com/dotnet/api/system.text.stringbuilder) -## Verison 0 +## Version 0 This version is the built-in IL Stub generation system that is triggered whenever a method marked with `DllImport` is invoked. diff --git a/docs/design/libraries/DllImportGenerator/RuntimeConsumption.md b/docs/design/libraries/DllImportGenerator/RuntimeConsumption.md deleted file mode 100644 index fa087a8db5ebd..0000000000000 --- a/docs/design/libraries/DllImportGenerator/RuntimeConsumption.md +++ /dev/null @@ -1,43 +0,0 @@ -# Integration into dotnet/runtime - -The prototype phase of the `DllImport` source generator is complete. The process and work done was tracked at [dotnet/runtime@43060](https://github.com/dotnet/runtime/issues/43060). The results of the prototype have provided us with some confidence that the current approach is viable and can move forward to consume the source generator in the .NET 7 timeframe. The plan for integration into the dotnet/runtime repository follows. - -Converting the prototype into a production ready product is required prior to consumption in the product. This means integration will be done in two phases, production-ready and consumption, that can be done in parallel in many cases. There is a third phase that is considered a stretch goal – productization. - -## Production-ready - -The following items must be considered to make this prototype production-ready. - -**Move source from dotnet/runtimelab** – Move the prototype source from its branch in [dotnet/runtimelab](https://github.com/dotnet/runtimelab/tree/feature/DllImportGenerator/DllImportGenerator) to [dotnet/runtime](https://github.com/dotnet/runtime). Guidance on destination can be found at [`project-guidelines.md`](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/project-guidelines.md) – plan is under `libraries/System.Runtime.InteropServices`. Commit history should be retained during this move. - - Includes unit and scenario test integration into the `libraries/` pattern. - -**Attributes into `System.Private.CoreLib`** – Prior to productization, triggering and support attributes should be moved into a global space for consumption by `NetCoreApp`. - -**Product impact tenets** – Size impact, security, and convention reviews. Patterns have been uncovered that could be improved upon in the source generation step. Collapsing some of these patterns would help with reducing size impact and addressing potential security issues. Code generation convention changes may result in API proposals for marshal helpers – see [struct marshalling](./StructMarshalling.md). - -**UX** – Source generators can run from a command line build as well as from the IDE. Running from within the IDE will impact the UX of the IDE and therefore performance investigations are needed to ensure the generator doesn't degrade the developer inner-loop. - -**Stakeholder feedback** – An exit criteria for the prototype was to reach out to stakeholders and get feedback on the experience and generated code. Responses to all feedback prior to product consumption is expected. - -## Consumption - -The following items must be considered to make the prototype consumable in [dotnet/runtime repository](https://github.com/dotnet/runtime). - -**In-box source generation** – Guidance for [providing an in-box source generator has been documented](https://github.com/dotnet/designs/blob/main/accepted/2021/InboxSourceGenerators.md). The document should be considered a primary source for best-practices that will eventually be needed for productization. - -**Versioning/Shipping/Servicing** – Partially captured in the "In-box source generation" document, but stated item is being called out. - -**Merge in feature branch** – Integration work for updates to `NetCoreApp` have started in [`feature/use-dllimport-generator`](https://github.com/dotnet/runtime/tree/feature/use-dllimport-generator). - - Question on the impact of [source build](https://github.com/dotnet/source-build) for dotnet/runtime. - -## Productization - -The following items must be considered to make this prototype into a product. - -**Localization** – We must ensure user observed messages are properly localized and adhere to the Globalization/Localization tenets. - -**API Review** – [`GeneratedDllImportAttribute`](https://github.com/dotnet/runtime/issues/46822); Supporting [attributes](https://github.com/dotnet/runtime/issues/46838) and marshalling helper types. - -**Distribution** – The consumption of the source generator product is assumed to be in-box and/or as a standalone NuPkg. If not distributed as NuPkg there is no known additional work here. - -**Documentation/Sample** – Productization will require new documentation and at least one official example.