Skip to content

Add note about when to use HGlobal allocator APIs. #10484

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Oct 2, 2024
Merged

Add note about when to use HGlobal allocator APIs. #10484

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cb7e549
Add note about when to use HGlobal allocator APIs.
AaronRobinsonMSFT Oct 1, 2024
2690f8c
Feedback
AaronRobinsonMSFT Oct 1, 2024
e3de014
Feedback
AaronRobinsonMSFT Oct 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions xml/System.Runtime.InteropServices/Marshal.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -303,6 +303,9 @@
<format type="text/markdown"><![CDATA[

## Remarks
> [!IMPORTANT]
> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.

<xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> is one of two memory allocation methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A?displayProperty=nameWithType> is the other.) This method exposes the Win32 [LocalAlloc](https://go.microsoft.com/fwlink/?LinkId=148628) function from Kernel32.dll.

When <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled.
Expand Down Expand Up @@ -383,6 +386,9 @@
<format type="text/markdown"><![CDATA[

## Remarks
> [!IMPORTANT]
> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.

<xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> is one of two memory allocation methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A?displayProperty=nameWithType> is the other.) This method exposes the Win32 [LocalAlloc](https://go.microsoft.com/fwlink/?LinkID=148628) function from Kernel32.dll.

When <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A> calls `LocalAlloc`, it passes a `LMEM_FIXED` flag, which causes the allocated memory to be locked in place. Also, the allocated memory is not zero-filled.
Expand Down Expand Up @@ -2656,6 +2662,9 @@
<format type="text/markdown"><![CDATA[

## Remarks
> [!IMPORTANT]
> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.

You can use <xref:System.Runtime.InteropServices.Marshal.FreeHGlobal%2A> to free any memory from the global heap allocated by <xref:System.Runtime.InteropServices.Marshal.AllocHGlobal%2A>, <xref:System.Runtime.InteropServices.Marshal.ReAllocHGlobal%2A>, or any equivalent unmanaged API method. If the `hglobal` parameter is <xref:System.IntPtr.Zero?displayProperty=nameWithType> the method does nothing.

<xref:System.Runtime.InteropServices.Marshal.FreeHGlobal%2A> exposes the [LocalFree](https://go.microsoft.com/fwlink/?LinkId=148640) function from Kernel32.DLL, which frees all bytes so that you can no longer use the memory pointed to by `hglobal`.
Expand Down Expand Up @@ -9569,6 +9578,9 @@ On .NET 6 and later versions, this method is functionally equivalent to <xref:Sy
<format type="text/markdown"><![CDATA[

## Remarks
> [!IMPORTANT]
> This native memory allocator is a legacy API that should be used exclusively when called for by specific Win32 APIs on the Windows platform. When targeting .NET 6 or later, use the <xref:System.Runtime.InteropServices.NativeMemory> class on all platforms to allocate native memory. When targeting .NET 6 or earlier, use <xref:System.Runtime.InteropServices.Marshal.AllocCoTaskMem%2A> on all platforms to allocate native memory.

<xref:System.Runtime.InteropServices.Marshal.ReAllocHGlobal%2A> is one of two memory reallocation API methods in the <xref:System.Runtime.InteropServices.Marshal> class. (<xref:System.Runtime.InteropServices.Marshal.ReAllocCoTaskMem%2A?displayProperty=nameWithType> is the other.)

This method exposes the Win32 [GlobalReAlloc](https://go.microsoft.com/fwlink/?LinkId=148780) function from Kernel32.dll. The returned pointer can differ from the original. If it is different, the contents of the original memory block have been copied to the new block, and the original memory block has been freed.
Expand Down