Memory Manager API for low-level native plug-ins

The IUnityMemoryManager memory manager API is a C++ interface that allows you to use Unity’s memory management and memory profiling in native plug-insA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
See in Glossary.

This API enables you to:

• Access Unity’s memory manager through a memory allocator.
• Track your plug-in’s memory use through Unity’s Memory ProfilerA window that helps you to optimize your game. It shows how much time is spent in the various areas of your game. For example, it can report the percentage of time spent rendering, animating, or in your game logic. More info
  See in Glossary package.

These features make it easier to manage and profile your plug-in’s memory allocations when compared to the equivalent C++ memory management methods.

The plug-in API is provided by the IUnityMemoryManager interface, which is declared in the IUnityMemoryManager.h header. The full reference for the API is available in this file. To find the header file:

• On Windows, Unity stores the header in the <UnityInstallPath>\Editor\Data\PluginAPI folder of your Unity installation.
• On macOS, right-click on the Unity application, and select Show Package Contents. The header is in Contents\PluginAPI.

You should be familiar with the following concepts to use this API effectively:

• C++ Pointers
• Memory in Unity
• The Memory Profiler package
• Memory allocator customization
• Predefined macros

Track memory use in Unity

To track your plug-in’s memory usage, use the Memory Profiler package to take a snapshot, then open the snapshot in the All Of Memory tab. When you use the IUnityMemoryManager to allocate memory, the Memory Profiler displays the plug-in’s memory allocations under the area and object name you assigned when you created each allocator.

The below screenshot shows the Memory Profiler package window displaying memory used by a native plug-in with memory allocated with the IUnityMemoryManager API. In this example, the method CreateAllocator was called, with “MyNativePlugin” as the areaName parameter, and “MyPluginAllocator” as the objectName parameter. For more information, see CreateAllocator.

For more information, see Snapshots.

Memory management limitations

This API enables you to use Unity’s memory management system when you develop native plug-ins. This has major benefits as described above, but there are still limitations. Unity’s memory management system:

• Isn’t automatically managed; you need to allocate and deallocate the memory yourself.
• Isn’t tracked and cleaned up by a garbage collector.

Since memory in native C++ isn’t managed, you need to keep track of any memory requirements your application has. This includes choosing the correct amount of memory to allocate and making sure you deallocate it when it’s no longer needed.

The IUnityMemoryManager API impacts performance because each allocation requires a virtual call. To minimize this performance impact, use the API to allocate larger blocks of memory less frequently. To handle smaller and more frequent allocations, use this API to allocate a single larger block, then write your own code to manage the memory within this block. Don’t use this API for frequent small allocations.

Additional resources

• Native Plug-in interface - Explains the base interface that this API inherits from.
• Native plug-insA platform-specific native code library that is created outside of Unity for use in Unity. Allows you can access features like OS calls and third-party code libraries that would otherwise not be available to Unity. More info
  See in Glossary - Explains what a native plug-in is.
• Memory allocator customization - Explains how to customize Unity’s internal memory allocators.