From 216d75a222f8ab8aced84ca892e85fd4bab67da9 Mon Sep 17 00:00:00 2001 From: Daan Date: Mon, 2 Sep 2019 10:48:49 -0700 Subject: [PATCH] Update readme.md --- readme.md | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/readme.md b/readme.md index 3720e5b6..6da3cf76 100644 --- a/readme.md +++ b/readme.md @@ -189,11 +189,17 @@ or via environment variables. - `MIMALLOC_SHOW_ERRORS=1`: show error and warning messages. - `MIMALLOC_LARGE_OS_PAGES=1`: use large OS pages when available; for some workloads this can significantly improve performance. Use `MIMALLOC_VERBOSE` to check if the large OS pages are enabled -- usually one needs - to explicitly allow large OS pages (as on [Windows][windows-huge] and [Linux][linux-huge]). + to explicitly allow large OS pages (as on [Windows][windows-huge] and [Linux][linux-huge]). However, sometimes + the OS is very slow to reserve contiguous physical memory for large OS pages so use with care on systems that + can have fragmented memory. - `MIMALLOC_EAGER_REGION_COMMIT=1`: on Windows, commit large (256MiB) regions eagerly. On Windows, these regions show in the working set even though usually just a small part is committed to physical memory. This is why it turned off by default on Windows as it looks not good in the task manager. However, in reality it is always better to turn it on as it improves performance and has no other drawbacks. +- `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 + `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. Still experimental. [linux-huge]: https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/5/html/tuning_and_optimizing_red_hat_enterprise_linux_for_oracle_9i_and_10g_databases/sect-oracle_9i_and_10g_tuning_guide-large_memory_optimization_big_pages_and_huge_pages-configuring_huge_pages_in_red_hat_enterprise_linux_4_or_5 [windows-huge]: https://docs.microsoft.com/en-us/sql/database-engine/configure-windows/enable-the-lock-pages-in-memory-option-windows?view=sql-server-2017 @@ -243,19 +249,23 @@ Note: unfortunately, at this time, dynamic overriding on macOS seems broken but ### Windows On Windows you need to link your program explicitly with the mimalloc -DLL, and use the C-runtime library as a DLL (the `/MD` or `/MDd` switch). -To ensure the mimalloc DLL gets loaded it is easiest to insert some +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 +in the same folder as the mimalloc DLL at runtime (as it as referred to by the mimalloc DLL). +The redirection DLL's ensure all calls to the C runtime malloc API get redirected to mimalloc. + +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()` -(or use the `/INCLUDE:mi_version` switch on the linker) +(or use the `/INCLUDE:mi_version` switch on the linker). See the `mimalloc-override-test` project +for an example on how to use this. -Due to the way mimalloc intercepts the standard malloc at runtime, it is best -to link to the mimalloc import library first on the command line so it gets -loaded right after the universal C runtime DLL (`ucrtbase`). See -the `mimalloc-override-test` project for an example. +The environment variable `MIMALLOC_DISABLE_REDIRECT=1` can be used to disable dynamic +overriding at run-time. Use `MIMALLOC_VERBOSE=1` to check if mimalloc successfully redirected. -Note: the current overriding on Windows works for most programs but some programs still have -trouble -- the `dev-exp` branch contains a newer way of overriding that is more -robust; try this out if you experience troubles. +(Note: in principle, it should be possible to patch existing executables +that are linked with the dynamic C runtime (`ucrtbase.dll`) by just putting the mimalloc DLL into +the import table (and putting `mimalloc-redirect.dll` in the same folder) +Such patching can be done for example with [CFF Explorer](https://ntcore.com/?page_id=388)). ## Static override