fix readme order
This commit is contained in:
Daan Leijen
parent
20126e1c6c
commit
6515829c84
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.
|
||||
- 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
|
||||
|
||||
@ -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!
|
||||
|
||||
|
||||
## 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
|
||||
|
||||
Last update: 2021-01-30
|
||||
|
||||
Loading…
Reference in New Issue
Block a user