mirror of
https://github.com/microsoft/mimalloc.git
synced 2025-05-06 23:39:31 +03:00
fix readme order
This commit is contained in:
Daan Leijen
parent
20126e1c6c
commit
6515829c84
1 changed files with 90 additions and 89 deletions
179
readme.md
179
readme.md
|
|
@ -352,95 +352,6 @@ When _mimalloc_ is built using debug mode, various checks are done at runtime to
|
||||||
- Double free's, and freeing invalid heap pointers are detected.
|
- Double free's, and freeing invalid heap pointers are detected.
|
||||||
- Corrupted free-lists and some forms of use-after-free are detected.
|
- Corrupted free-lists and some forms of use-after-free are detected.
|
||||||
|
|
||||||
## Tools
|
|
||||||
|
|
||||||
Generally, we recommend using the standard allocator with memory tracking tools, but mimalloc
|
|
||||||
can also be build to support the [address sanitizer][asan] or the excellent [Valgrind] tool.
|
|
||||||
Moreover, it can be build to support Windows event tracing ([ETW]).
|
|
||||||
This has a small performance overhead but does allow detecting memory leaks and byte-precise
|
|
||||||
buffer overflows directly on final executables. See also the `test/test-wrong.c` file to test with various tools.
|
|
||||||
|
|
||||||
### Valgrind
|
|
||||||
|
|
||||||
To build with valgrind support, use the `MI_TRACK_VALGRIND=ON` cmake option:
|
|
||||||
|
|
||||||
```
|
|
||||||
> cmake ../.. -DMI_TRACK_VALGRIND=ON
|
|
||||||
```
|
|
||||||
|
|
||||||
This can also be combined with secure mode or debug mode.
|
|
||||||
You can then run your programs directly under valgrind:
|
|
||||||
|
|
||||||
```
|
|
||||||
> valgrind <myprogram>
|
|
||||||
```
|
|
||||||
|
|
||||||
If you rely on overriding `malloc`/`free` by mimalloc (instead of using the `mi_malloc`/`mi_free` API directly),
|
|
||||||
you also need to tell `valgrind` to not intercept those calls itself, and use:
|
|
||||||
|
|
||||||
```
|
|
||||||
> MIMALLOC_SHOW_STATS=1 valgrind --soname-synonyms=somalloc=*mimalloc* -- <myprogram>
|
|
||||||
```
|
|
||||||
|
|
||||||
By setting the `MIMALLOC_SHOW_STATS` environment variable you can check that mimalloc is indeed
|
|
||||||
used and not the standard allocator. Even though the [Valgrind option][valgrind-soname]
|
|
||||||
is called `--soname-synonyms`, this also
|
|
||||||
works when overriding with a static library or object file. Unfortunately, it is not possible to
|
|
||||||
dynamically override mimalloc using `LD_PRELOAD` together with `valgrind`.
|
|
||||||
See also the `test/test-wrong.c` file to test with `valgrind`.
|
|
||||||
|
|
||||||
Valgrind support is in its initial development -- please report any issues.
|
|
||||||
|
|
||||||
[Valgrind]: https://valgrind.org/
|
|
||||||
[valgrind-soname]: https://valgrind.org/docs/manual/manual-core.html#opt.soname-synonyms
|
|
||||||
|
|
||||||
### ASAN
|
|
||||||
|
|
||||||
To build with the address sanitizer, use the `-DMI_TRACK_ASAN=ON` cmake option:
|
|
||||||
|
|
||||||
```
|
|
||||||
> cmake ../.. -DMI_TRACK_ASAN=ON
|
|
||||||
```
|
|
||||||
|
|
||||||
This can also be combined with secure mode or debug mode.
|
|
||||||
You can then run your programs as:'
|
|
||||||
|
|
||||||
```
|
|
||||||
> ASAN_OPTIONS=verbosity=1 <myprogram>
|
|
||||||
```
|
|
||||||
|
|
||||||
When you link a program with an address sanitizer build of mimalloc, you should
|
|
||||||
generally compile that program too with the address sanitizer enabled.
|
|
||||||
For example, assuming you build mimalloc in `out/debug`:
|
|
||||||
|
|
||||||
```
|
|
||||||
clang -g -o test-wrong -Iinclude test/test-wrong.c out/debug/libmimalloc-asan-debug.a -lpthread -fsanitize=address -fsanitize-recover=address
|
|
||||||
```
|
|
||||||
|
|
||||||
Since the address sanitizer redirects the standard allocation functions, on some platforms (macOSX for example)
|
|
||||||
it is required to compile mimalloc with `-DMI_OVERRIDE=OFF`.
|
|
||||||
Adress sanitizer support is in its initial development -- please report any issues.
|
|
||||||
|
|
||||||
[asan]: https://github.com/google/sanitizers/wiki/AddressSanitizer
|
|
||||||
|
|
||||||
### ETW
|
|
||||||
|
|
||||||
Event tracing for Windows ([ETW]) provides a high performance way to capture all allocations though
|
|
||||||
mimalloc and analyze them later. To build with ETW support, use the `-DMI_TRACE_ETW=ON` cmake option.
|
|
||||||
|
|
||||||
You can then capture an allocation trace using the Windows performance recorder (WPR), using the
|
|
||||||
`src/prim/windows/etw-mimalloc.wprp` profile. In an admin prompt, you can use:
|
|
||||||
```
|
|
||||||
> wpr -start src\prim\windows\etw-mimalloc.wprp -filemode
|
|
||||||
> <my_mimalloc_program>
|
|
||||||
> wpr -stop <my_mimalloc_program>.etl
|
|
||||||
```
|
|
||||||
and then open `<my_mimalloc_program>.etl` in the Windows Performance Analyzer (WPA), or
|
|
||||||
use a tool like [TraceControl] that is specialized for analyzing mimalloc traces.
|
|
||||||
|
|
||||||
[ETW]: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/event-tracing-for-windows
|
|
||||||
[TraceControl]: https://github.com/xinglonghe/TraceControl
|
|
||||||
|
|
||||||
|
|
||||||
# Overriding Standard Malloc
|
# Overriding Standard Malloc
|
||||||
|
|
||||||
|
|
@ -531,6 +442,96 @@ This is provided by [`mimalloc-override.h`](https://github.com/microsoft/mimallo
|
||||||
under your control or otherwise mixing of pointers from different heaps may occur!
|
under your control or otherwise mixing of pointers from different heaps may occur!
|
||||||
|
|
||||||
|
|
||||||
|
## Tools
|
||||||
|
|
||||||
|
Generally, we recommend using the standard allocator with memory tracking tools, but mimalloc
|
||||||
|
can also be build to support the [address sanitizer][asan] or the excellent [Valgrind] tool.
|
||||||
|
Moreover, it can be build to support Windows event tracing ([ETW]).
|
||||||
|
This has a small performance overhead but does allow detecting memory leaks and byte-precise
|
||||||
|
buffer overflows directly on final executables. See also the `test/test-wrong.c` file to test with various tools.
|
||||||
|
|
||||||
|
### Valgrind
|
||||||
|
|
||||||
|
To build with [valgrind] support, use the `MI_TRACK_VALGRIND=ON` cmake option:
|
||||||
|
|
||||||
|
```
|
||||||
|
> cmake ../.. -DMI_TRACK_VALGRIND=ON
|
||||||
|
```
|
||||||
|
|
||||||
|
This can also be combined with secure mode or debug mode.
|
||||||
|
You can then run your programs directly under valgrind:
|
||||||
|
|
||||||
|
```
|
||||||
|
> valgrind <myprogram>
|
||||||
|
```
|
||||||
|
|
||||||
|
If you rely on overriding `malloc`/`free` by mimalloc (instead of using the `mi_malloc`/`mi_free` API directly),
|
||||||
|
you also need to tell `valgrind` to not intercept those calls itself, and use:
|
||||||
|
|
||||||
|
```
|
||||||
|
> MIMALLOC_SHOW_STATS=1 valgrind --soname-synonyms=somalloc=*mimalloc* -- <myprogram>
|
||||||
|
```
|
||||||
|
|
||||||
|
By setting the `MIMALLOC_SHOW_STATS` environment variable you can check that mimalloc is indeed
|
||||||
|
used and not the standard allocator. Even though the [Valgrind option][valgrind-soname]
|
||||||
|
is called `--soname-synonyms`, this also
|
||||||
|
works when overriding with a static library or object file. Unfortunately, it is not possible to
|
||||||
|
dynamically override mimalloc using `LD_PRELOAD` together with `valgrind`.
|
||||||
|
See also the `test/test-wrong.c` file to test with `valgrind`.
|
||||||
|
|
||||||
|
Valgrind support is in its initial development -- please report any issues.
|
||||||
|
|
||||||
|
[Valgrind]: https://valgrind.org/
|
||||||
|
[valgrind-soname]: https://valgrind.org/docs/manual/manual-core.html#opt.soname-synonyms
|
||||||
|
|
||||||
|
### ASAN
|
||||||
|
|
||||||
|
To build with the address sanitizer, use the `-DMI_TRACK_ASAN=ON` cmake option:
|
||||||
|
|
||||||
|
```
|
||||||
|
> cmake ../.. -DMI_TRACK_ASAN=ON
|
||||||
|
```
|
||||||
|
|
||||||
|
This can also be combined with secure mode or debug mode.
|
||||||
|
You can then run your programs as:'
|
||||||
|
|
||||||
|
```
|
||||||
|
> ASAN_OPTIONS=verbosity=1 <myprogram>
|
||||||
|
```
|
||||||
|
|
||||||
|
When you link a program with an address sanitizer build of mimalloc, you should
|
||||||
|
generally compile that program too with the address sanitizer enabled.
|
||||||
|
For example, assuming you build mimalloc in `out/debug`:
|
||||||
|
|
||||||
|
```
|
||||||
|
clang -g -o test-wrong -Iinclude test/test-wrong.c out/debug/libmimalloc-asan-debug.a -lpthread -fsanitize=address -fsanitize-recover=address
|
||||||
|
```
|
||||||
|
|
||||||
|
Since the address sanitizer redirects the standard allocation functions, on some platforms (macOSX for example)
|
||||||
|
it is required to compile mimalloc with `-DMI_OVERRIDE=OFF`.
|
||||||
|
Adress sanitizer support is in its initial development -- please report any issues.
|
||||||
|
|
||||||
|
[asan]: https://github.com/google/sanitizers/wiki/AddressSanitizer
|
||||||
|
|
||||||
|
### ETW
|
||||||
|
|
||||||
|
Event tracing for Windows ([ETW]) provides a high performance way to capture all allocations though
|
||||||
|
mimalloc and analyze them later. To build with ETW support, use the `-DMI_TRACE_ETW=ON` cmake option.
|
||||||
|
|
||||||
|
You can then capture an allocation trace using the Windows performance recorder (WPR), using the
|
||||||
|
`src/prim/windows/etw-mimalloc.wprp` profile. In an admin prompt, you can use:
|
||||||
|
```
|
||||||
|
> wpr -start src\prim\windows\etw-mimalloc.wprp -filemode
|
||||||
|
> <my_mimalloc_program>
|
||||||
|
> wpr -stop <my_mimalloc_program>.etl
|
||||||
|
```
|
||||||
|
and then open `<my_mimalloc_program>.etl` in the Windows Performance Analyzer (WPA), or
|
||||||
|
use a tool like [TraceControl] that is specialized for analyzing mimalloc traces.
|
||||||
|
|
||||||
|
[ETW]: https://learn.microsoft.com/en-us/windows-hardware/test/wpt/event-tracing-for-windows
|
||||||
|
[TraceControl]: https://github.com/xinglonghe/TraceControl
|
||||||
|
|
||||||
|
|
||||||
# Performance
|
# Performance
|
||||||
|
|
||||||
Last update: 2021-01-30
|
Last update: 2021-01-30
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue