kiper220/mimalloc
1
0
Fork 0
mirror of https://github.com/microsoft/mimalloc.git synced 2025-05-05 06:59:32 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update readme.md

Browse source
This commit is contained in:
Daan 2020-01-22 18:16:40 -08:00 • committed by GitHub
parent b7aef989e8
commit 6a744a8549
WARNING! Although there is a key with this ID in the database it does not verify this commit! This commit is SUSPICIOUS.
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 15 additions and 14 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
readme.md
View file

@ -10,15 +10,15 @@
mimalloc (pronounced "me-malloc") mimalloc (pronounced "me-malloc")
is a general purpose allocator with excellent [performance](#performance) characteristics. is a general purpose allocator with excellent [performance](#performance) characteristics.
Initially developed by Daan Leijen for the run-time systems of the Initially developed by Daan Leijen for the run-time systems of the
[Koka](https://github.com/koka-lang/koka) and [Lean](https://github.com/leanprover/lean) languages. [Koka](https://github.com/koka-lang/koka) and [Lean](https://github.com/leanprover/lean) languages.
Latest release:`v1.4.0` (2020-01-22).
It is a drop-in replacement for `malloc` and can be used in other programs It is a drop-in replacement for `malloc` and can be used in other programs
without code changes, for example, on dynamically linked ELF-based systems (Linux, BSD, etc.) you can use it as: without code changes, for example, on dynamically linked ELF-based systems (Linux, BSD, etc.) you can use it as:
``` ```
> LD_PRELOAD=/usr/bin/libmimalloc.so myprogram > LD_PRELOAD=/usr/bin/libmimalloc.so myprogram
``` ```
It also has an easy way to override the allocator in [Windows](#override_on_windows). Notable aspects of the design include:
Notable aspects of the design include:
- __small and consistent__: the library is about 6k LOC using simple and - __small and consistent__: the library is about 6k LOC using simple and
consistent data structures. This makes it very suitable consistent data structures. This makes it very suitable
@ -45,9 +45,10 @@ Notable aspects of the design include:
times (_wcat_), bounded space overhead (~0.2% meta-data, with at most 12.5% waste in allocation sizes), times (_wcat_), bounded space overhead (~0.2% meta-data, with at most 12.5% waste in allocation sizes),
and has no internal points of contention using only atomic operations. and has no internal points of contention using only atomic operations.
- __fast__: In our benchmarks (see [below](#performance)), - __fast__: In our benchmarks (see [below](#performance)),
_mimalloc_ always outperforms all other leading allocators (_jemalloc_, _tcmalloc_, _Hoard_, etc), _mimalloc_ outperforms other leading allocators (_jemalloc_, _tcmalloc_, _Hoard_, etc),
and usually uses less memory (up to 25% more in the worst case). A nice property and usually uses less memory (up to 25% more in the worst case). A nice property
is that it does consistently well over a wide range of benchmarks. is that it does consistently well over a wide range of benchmarks. There is also good huge OS page
support for larger server programs.
The [documentation](https://microsoft.github.io/mimalloc) gives a full overview of the API. The [documentation](https://microsoft.github.io/mimalloc) gives a full overview of the API.
You can read more on the design of _mimalloc_ in the [technical report](https://www.microsoft.com/en-us/research/publication/mimalloc-free-list-sharding-in-action) which also has detailed benchmark results. You can read more on the design of _mimalloc_ in the [technical report](https://www.microsoft.com/en-us/research/publication/mimalloc-free-list-sharding-in-action) which also has detailed benchmark results.
@ -56,8 +57,8 @@ Enjoy!
### Releases ### Releases
* 2020-01-22, `v1.4.0`: stable release 1.4: delayed OS page reset with (much) better performance * 2020-01-22, `v1.4.0`: stable release 1.4: improved performance for delayed OS page reset,
(when page reset is enabled), more eager concurrent free, addition of STL allocator, fixed potential memory leak. more eager concurrent free, addition of STL allocator, fixed potential memory leak.
* 2020-01-15, `v1.3.0`: stable release 1.3: bug fixes, improved randomness and [stronger * 2020-01-15, `v1.3.0`: stable release 1.3: bug fixes, improved randomness and [stronger
free list encoding](https://github.com/microsoft/mimalloc/blob/783e3377f79ee82af43a0793910a9f2d01ac7863/include/mimalloc-internal.h#L396) in secure mode. free list encoding](https://github.com/microsoft/mimalloc/blob/783e3377f79ee82af43a0793910a9f2d01ac7863/include/mimalloc-internal.h#L396) in secure mode.
* 2019-12-22, `v1.2.2`: stable release 1.2: minor updates. * 2019-12-22, `v1.2.2`: stable release 1.2: minor updates.
@ -189,7 +190,7 @@ malloc requested: 32.8 mb
The above model of using the `mi_` prefixed API is not always possible The above model of using the `mi_` prefixed API is not always possible
though in existing programs that already use the standard malloc interface, though in existing programs that already use the standard malloc interface,
and another option is to override the standard malloc interface and another option is to override the standard malloc interface
completely and redirect all calls to the _mimalloc_ library instead. completely and redirect all calls to the _mimalloc_ library instead .
## Environment Options ## Environment Options
@ -215,7 +216,7 @@ or via environment variables.
real drawbacks and may improve performance by a little. real drawbacks and may improve performance by a little.
--> -->
- `MIMALLOC_RESERVE_HUGE_OS_PAGES=N`: where N is the number of 1GiB huge OS pages. This reserves the huge pages at - `MIMALLOC_RESERVE_HUGE_OS_PAGES=N`: where N is the number of 1GiB huge OS pages. This reserves the huge pages at
startup and can give quite a performance improvement on long running workloads. Usually it is better to not use startup and can give quite a (latency) performance improvement on long running workloads. Usually it is better to not use
`MIMALLOC_LARGE_OS_PAGES` in combination with this setting. Just like large OS pages, use with care as reserving `MIMALLOC_LARGE_OS_PAGES` in combination with this setting. Just like large OS pages, use with care as reserving
contiguous physical memory can take a long time when memory is fragmented (but reserving the huge pages is done at contiguous physical memory can take a long time when memory is fragmented (but reserving the huge pages is done at
startup only once). startup only once).
@ -236,7 +237,7 @@ Overriding the standard `malloc` can be done either _dynamically_ or _statically
This is the recommended way to override the standard malloc interface. This is the recommended way to override the standard malloc interface.
### Linux, BSD ### Override on Linux, BSD
On these ELF-based systems we preload the mimalloc shared On these ELF-based systems we preload the mimalloc shared
library so all calls to the standard `malloc` interface are library so all calls to the standard `malloc` interface are
@ -255,7 +256,7 @@ or run with the debug version to get detailed statistics:
> env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram > env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram
``` ```
### MacOS ### Override on MacOS
On macOS we can also preload the mimalloc shared On macOS we can also preload the mimalloc shared
library so all calls to the standard `malloc` interface are library so all calls to the standard `malloc` interface are
@ -270,9 +271,9 @@ the [shell](https://stackoverflow.com/questions/43941322/dyld-insert-libraries-i
Note: unfortunately, at this time, dynamic overriding on macOS seems broken but it is Note: unfortunately, at this time, dynamic overriding on macOS seems broken but it is
actively worked on to fix this (see issue [`#50`](https://github.com/microsoft/mimalloc/issues/50)). actively worked on to fix this (see issue [`#50`](https://github.com/microsoft/mimalloc/issues/50)).
### Windows ### Override on Windows
Overriding on Windows is robust but requires that you link your program explicitly with <span id="override_on_windows">Overriding on Windows</span> is robust but requires that you link your program explicitly with
the mimalloc DLL and use the C-runtime library as a DLL (using the `/MD` or `/MDd` switch). the mimalloc DLL and use the C-runtime library as a DLL (using the `/MD` or `/MDd` switch).
Moreover, you need to ensure the `mimalloc-redirect.dll` (or `mimalloc-redirect32.dll`) is available Moreover, you need to ensure the `mimalloc-redirect.dll` (or `mimalloc-redirect32.dll`) is available
in the same folder as the main `mimalloc-override.dll` at runtime (as it is a dependency). in the same folder as the main `mimalloc-override.dll` at runtime (as it is a dependency).
@ -283,7 +284,7 @@ To ensure the mimalloc DLL is loaded at run-time it is easiest to insert some
call to the mimalloc API in the `main` function, like `mi_version()` call to the mimalloc API in the `main` function, like `mi_version()`
(or use the `/INCLUDE:mi_version` switch on the linker). See the `mimalloc-override-test` project (or use the `/INCLUDE:mi_version` switch on the linker). See the `mimalloc-override-test` project
for an example on how to use this. For best performance on Windows with C++, it for an example on how to use this. For best performance on Windows with C++, it
is highly recommended to also override the `new`/`delete` operations (by including is also recommended to also override the `new`/`delete` operations (by including
[`mimalloc-new-delete.h`](https://github.com/microsoft/mimalloc/blob/master/include/mimalloc-new-delete.h) a single(!) source file in your project). [`mimalloc-new-delete.h`](https://github.com/microsoft/mimalloc/blob/master/include/mimalloc-new-delete.h) a single(!) source file in your project).
The environment variable `MIMALLOC_DISABLE_REDIRECT=1` can be used to disable dynamic The environment variable `MIMALLOC_DISABLE_REDIRECT=1` can be used to disable dynamic