From cfd39bdb4ddfa9ced1297c21d8be68951398d1f2 Mon Sep 17 00:00:00 2001 From: annaaniol Date: Mon, 13 Aug 2018 13:58:06 -0700 Subject: Update the dllmap design doc (3) --- Documentation/design-docs/dllmap.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'Documentation') diff --git a/Documentation/design-docs/dllmap.md b/Documentation/design-docs/dllmap.md index 8e52358705..3af0e1bd9b 100644 --- a/Documentation/design-docs/dllmap.md +++ b/Documentation/design-docs/dllmap.md @@ -50,16 +50,18 @@ There will be a diagnostic mechanism available to monitor dllmap related issues. ### Interaction with Dllmap -#### Mono compatibility -Dllmap should be easy to use. It’s possible to achieve this easily by keeping Mono-compatible style of XML mapping configuration file. -It’s described [here](http://www.mono-project.com/docs/advanced/pinvoke/dllmap/). -Thanks to compatibility with Mono, users will be able to migrate from Mono’s Dllmap to .NET Core cross-platform applications. - -#### Flexibility -For users, who want to manage their cross-platform dll imports in their own way, dll-load specific events will be exposed. -Users will be able to subscribe to these events and implement any library/entrypoint loading policies. -For example, they will be able to replace XML parsing with JSON or any other file format parsing and provide configuration files in the most suitable format. -This is something that Mono doesn't have. Details are described in the Design section. +#### Mono users: Mono compatibility +The Dllmap method is meant as a compatibility feature for Mono and provides users with a straightforward migration story from Mono to .NET Core applications having p/invokes. +The default dllmap will consume a configuration file of [the same style](http://www.mono-project.com/docs/advanced/pinvoke/dllmap/) as Mono does. +Users will be able to use their old Mono configuration files when specifying the mapping for .NET Core applications. +Configuration files must be placed next to the assemblies that they describe. + +#### New users: flexibility +New users, who plan to support p/invokes in their cross-platform applications, should implement their custom mapping policies that satisfies their needs. +The runtime will use two dll specific callbacks on each dll load attempt (one on loading a library, one on determining an entrypoint). +The user’s code can subscribe to these callbacks and define any mapping strategy. +Users should keep in mind that the default dllmap methods are provided for an easier migration from Mono. +For newcomers, it’s highly recommended to use callbacks and implement their own handers. Details of the callback strategy are described in the Design section. ### Usage example (XML configuration) @@ -87,7 +89,7 @@ With this file, all `GetCurrentProcessId` calls get automatically mapped to `get When mapping a function into another function, both the source and the target functions must take the same number of arguments of compatible type. Otherwise, the mapping will not work. This is a very basic scenario and it can be extended to different operating systems, libraries and entrypoints. -It assumes that user does not implement any custom actions (handlers) but uses the default dllmap behavior. +It assumes that user does not implement any custom actions (handlers) but uses the default Mono-like dllmap behavior. ## Design ### XML configuration file @@ -197,7 +199,7 @@ Callbacks can be executed for all assemblies except `System.Private.CoreLib`. IntPtr ResolveNativeEntrypointName(string entrypointName, HMOD hmod) ``` -**Dotnet.corefx.labs.dll [managed code]** +**corefx.labs [managed code]** - Implements default handlers - `LoadNativeDllViaDllMap` and `GetEntrypointViaDllMap` - To avoid infinite looping, `LoadNativeDllViaDllMap` takes a lock and releases it after the default library loading process is completed ```c# -- cgit v1.2.3