1.. _Windows_C_Dynamic_Memory_Interface_Replacement:
2
3Windows\* OS C/C++ Dynamic Memory Interface Replacement
4=======================================================
5
6
7Release version of the proxy library is ``tbbmalloc_proxy.dll``, debug
8version is ``tbbmalloc_proxy_debug.dll``.
9
10
11The following dynamic memory functions are replaced:
12
13
14-  Standard C library functions: ``malloc``, ``calloc``, ``realloc``,
15   ``free``
16
17
18-  Replaceable global C++ operators ``new`` and ``delete``
19
20
21-  Microsoft\* C run-time library functions: ``_msize``,
22   ``_aligned_malloc``, ``_aligned_realloc``, ``_aligned_free``,
23   ``_aligned_msize``
24
25
26.. note::
27   Replacement of memory allocation functions is not supported for
28   Universal Windows Platform applications.
29
30
31To do the replacement use one of the following methods:
32
33
34-  Add the following header to a source code of any binary which is
35   loaded during application startup.
36
37
38   ::
39
40
41      #include "oneapi/tbb/tbbmalloc_proxy.h"
42
43
44-  Alternatively, add the following parameters to the linker options for
45   the .exe or .dll file that is loaded during application startup.
46
47
48   For 32-bit code (note the triple underscore):
49
50
51   ::
52
53
54      tbbmalloc_proxy.lib /INCLUDE:"___TBB_malloc_proxy"
55
56
57   For 64-bit code (note the double underscore):
58
59
60   ::
61
62
63      tbbmalloc_proxy.lib /INCLUDE:"__TBB_malloc_proxy"
64
65
66The OS program loader must be able to find the proxy library and the
67scalable memory allocator library at program load time. For that you may
68include the directory containing the libraries in the ``PATH``
69environment variable.
70
71
72The replacement uses in-memory binary instrumentation of Visual C++\*
73runtime libraries. To ensure correctness, it must first recognize a
74subset of dynamic memory functions in these libraries. If a problem
75occurs, the replacement is skipped, and the program continues to use the
76standard memory allocation functions. You can use the ``TBB_malloc_replacement_log``
77function to check if the replacement has succeeded and to get additional information.
78
79
80Set the ``TBB_MALLOC_DISABLE_REPLACEMENT`` environment variable to 1 to
81disable replacement for a specific program invocation. In this case, the
82program will use standard dynamic memory allocation functions. Note that
83the oneTBB memory allocation libraries are still required for the
84program to start even if their usage is disabled.
85
86