From b74f9b979f6d9646d2d11d436893d2d8d1ac18af Mon Sep 17 00:00:00 2001 From: daan Date: Sat, 10 Aug 2019 17:27:07 -0700 Subject: [PATCH] update documentation --- doc/mimalloc-doc.h | 71 ++++++++++++++++++++++++++------ docs/group__options.html | 42 +++++++++++++------ docs/group__options.js | 11 +++-- docs/group__posix.html | 64 ++++++++++++++++++++++++++-- docs/group__posix.js | 2 + docs/mimalloc-doc_8h_source.html | 27 +++++++----- docs/navtreeindex0.js | 29 ++++++++----- docs/overrides.html | 19 +++++---- docs/search/all_6.js | 9 +++- docs/search/enumvalues_1.js | 7 +++- docs/search/functions_0.js | 2 + docs/using.html | 11 ++++- 12 files changed, 231 insertions(+), 63 deletions(-) diff --git a/doc/mimalloc-doc.h b/doc/mimalloc-doc.h index 57b7dd4c..e4f8590f 100644 --- a/doc/mimalloc-doc.h +++ b/doc/mimalloc-doc.h @@ -609,15 +609,23 @@ bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_all_blocks, mi_block /// Runtime options. typedef enum mi_option_e { - mi_option_page_reset, ///< Reset page memory when it becomes free. - mi_option_cache_reset, ///< Reset segment memory when a segment is cached. - mi_option_pool_commit, ///< Commit segments in large pools. + // stable options mi_option_show_stats, ///< Print statistics to `stderr` when the program is done. mi_option_show_errors, ///< Print error messages to `stderr`. mi_option_verbose, ///< Print verbose messages to `stderr`. + // the following options are experimental + mi_option_secure, ///< Experimental + mi_option_eager_commit, ///< Eagerly commit segments (4MiB) (enabled by default). + mi_option_eager_region_commit, ///< Eagerly commit large (256MiB) memory regions (enabled by default except on Windows) + mi_option_large_os_pages, ///< Use large OS pages if possible + mi_option_page_reset, ///< Reset page memory when it becomes free. + mi_option_cache_reset, ///< Reset segment memory when a segment is cached. + mi_option_reset_decommits, ///< Experimental + mi_option_reset_discards, ///< Experimental _mi_option_last } mi_option_t; + bool mi_option_enabled(mi_option_t option); void mi_option_enable(mi_option_t option, bool enable); void mi_option_enable_default(mi_option_t option, bool enable); @@ -654,12 +662,17 @@ void mi_free_size(void* p, size_t size); void mi_free_size_aligned(void* p, size_t size, size_t alignment); void mi_free_aligned(void* p, size_t alignment); -/// Only defined in C++ compilation; raise `std::bad_alloc` exception on failure. +/// raise `std::bad_alloc` exception on failure. void* mi_new(std::size_t n) noexcept(false); -/// Only defined in C++ compilation; raise `std::bad_alloc` exception on failure. +/// raise `std::bad_alloc` exception on failure. void* mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false); +/// return `NULL` on failure. +void* mi_new_nothrow(size_t n); +`` +/// return `NULL` on failure. +void* mi_new_aligned_nothrow(size_t n, size_t alignment); /// \} @@ -791,6 +804,25 @@ completely and redirect all calls to the _mimalloc_ library instead. See \ref overrides for more info. +## Environment Options + +You can set further options either programmatically (using [`mi_option_set`](https://microsoft.github.io/mimalloc/group__options.html)), +or via environment variables. + +- `MIMALLOC_SHOW_STATS=1`: show statistics when the program terminates. +- `MIMALLOC_VERBOSE=1`: show verbose messages. +- `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]). +- `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. + +[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 + */ /*! \page overrides Overriding Malloc @@ -801,17 +833,14 @@ Overriding the standard `malloc` can be done either _dynamically_ or _statically This is the recommended way to override the standard malloc interface. -### Unix, BSD, macOS + +### Linux, BSD On these systems we preload the mimalloc shared library so all calls to the standard `malloc` interface are resolved to the _mimalloc_ library. -- `env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram` (on Linux, BSD, etc.) -- `env DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram` (On macOS) - - Note certain security restrictions may apply when doing this from - the [shell](https://stackoverflow.com/questions/43941322/dyld-insert-libraries-ignored-when-calling-application-through-bash). +- `env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram` You can set extra environment variables to check that mimalloc is running, like: @@ -823,18 +852,36 @@ or run with the debug version to get detailed statistics: env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram ``` +### MacOS + +On macOS we can also preload the mimalloc shared +library so all calls to the standard `malloc` interface are +resolved to the _mimalloc_ library. + +- `env DYLD_FORCE_FLAT_NAMESPACE=1 DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram` + +Note that certain security restrictions may apply when doing this from +the [shell](https://stackoverflow.com/questions/43941322/dyld-insert-libraries-ignored-when-calling-application-through-bash). + +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)). + ### 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 -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) 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. +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. ## Static override diff --git a/docs/group__options.html b/docs/group__options.html index eddc2b39..e8a0bbd6 100644 --- a/docs/group__options.html +++ b/docs/group__options.html @@ -112,13 +112,19 @@ $(document).ready(function(){initNavTree('group__options.html','');});

Enumerations

enum  mi_option_t {
-  mi_option_page_reset, -mi_option_cache_reset, -mi_option_pool_commit, -mi_option_show_stats, -
-  mi_option_show_errors, +  mi_option_show_stats, +mi_option_show_errors, mi_option_verbose, +mi_option_secure, +
+  mi_option_eager_commit, +mi_option_eager_region_commit, +mi_option_large_os_pages, +mi_option_page_reset, +
+  mi_option_cache_reset, +mi_option_reset_decommits, +mi_option_reset_discards, _mi_option_last
} @@ -157,18 +163,28 @@ Functions

Runtime options.

- - - - + + + + + + + +
Enumerator
mi_option_page_reset 

Reset page memory when it becomes free.

-
mi_option_cache_reset 

Reset segment memory when a segment is cached.

-
mi_option_pool_commit 

Commit segments in large pools.

-
mi_option_show_stats 

Print statistics to stderr when the program is done.

+
Enumerator
mi_option_show_stats 

Print statistics to stderr when the program is done.

mi_option_show_errors 

Print error messages to stderr.

mi_option_verbose 

Print verbose messages to stderr.

mi_option_secure 

Experimental.

+
mi_option_eager_commit 

Eagerly commit segments (4MiB) (enabled by default).

+
mi_option_eager_region_commit 

Eagerly commit large (256MiB) memory regions (enabled by default except on Windows)

+
mi_option_large_os_pages 

Use large OS pages if possible.

+
mi_option_page_reset 

Reset page memory when it becomes free.

+
mi_option_cache_reset 

Reset segment memory when a segment is cached.

+
mi_option_reset_decommits 

Experimental.

+
mi_option_reset_discards 

Experimental.

+
_mi_option_last 
diff --git a/docs/group__options.js b/docs/group__options.js index 19cb95a0..485dc83d 100644 --- a/docs/group__options.js +++ b/docs/group__options.js @@ -1,12 +1,17 @@ var group__options = [ [ "mi_option_t", "group__options.html#gafebf7ed116adb38ae5218bc3ce06884c", [ - [ "mi_option_page_reset", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968", null ], - [ "mi_option_cache_reset", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07", null ], - [ "mi_option_pool_commit", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1d7948dd9565c26d411e6dbdf549be79", null ], [ "mi_option_show_stats", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca0957ef73b2550764b4840edf48422fda", null ], [ "mi_option_show_errors", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cafbf4822e5c00732c5984b32a032837f0", null ], [ "mi_option_verbose", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca7c8b7bf5281c581bad64f5daa6442777", null ], + [ "mi_option_secure", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca083ee20765063fc6d727e11d33cf378f", null ], + [ "mi_option_eager_commit", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1e8de72c93da7ff22d91e1e27b52ac2b", null ], + [ "mi_option_eager_region_commit", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca32ce97ece29f69e82579679cf8a307ad", null ], + [ "mi_option_large_os_pages", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca4192d491200d0055df0554d4cf65054e", null ], + [ "mi_option_page_reset", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968", null ], + [ "mi_option_cache_reset", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07", null ], + [ "mi_option_reset_decommits", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac81ee965b130fa81238913a3c239d536", null ], + [ "mi_option_reset_discards", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cab3a837b5ceee250e14e051dbee2a441b", null ], [ "_mi_option_last", "group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca5b4357b74be0d87568036c32eb1a2e4a", null ] ] ], [ "mi_option_enable", "group__options.html#ga6d45a20a3131f18bc351b69763b38ce4", null ], diff --git a/docs/group__posix.html b/docs/group__posix.html index 3bd2378a..6d0ca57c 100644 --- a/docs/group__posix.html +++ b/docs/group__posix.html @@ -137,11 +137,17 @@ Functions void mi_free_aligned (void *p, size_t alignment)   void * mi_new (std::size_t n) noexcept(false) - Only defined in C++ compilation; raise std::bad_alloc exception on failure. More...
+ raise std::bad_alloc exception on failure. More...
  void * mi_new_aligned (std::size_t n, std::align_val_t alignment) noexcept(false) - Only defined in C++ compilation; raise std::bad_alloc exception on failure. More...
+ raise std::bad_alloc exception on failure. More...
  +void * mi_new_nothrow (size_t n) + return NULL on failure. More...
+  +void * mi_new_aligned_nothrow (size_t n, size_t alignment) + return NULL on failure. More...
+ 

Detailed Description

mi_ prefixed implementations of various Posix, Unix, and C++ allocation functions.

@@ -405,7 +411,7 @@ Functions
-

Only defined in C++ compilation; raise std::bad_alloc exception on failure.

+

raise std::bad_alloc exception on failure.

@@ -443,7 +449,57 @@ Functions
-

Only defined in C++ compilation; raise std::bad_alloc exception on failure.

+

raise std::bad_alloc exception on failure.

+ +
+ + +

◆ mi_new_aligned_nothrow()

+ +
+
+ + + + + + + + + + + + + + + + + + +
void* mi_new_aligned_nothrow (size_t n,
size_t alignment 
)
+
+ +

return NULL on failure.

+ +
+
+ +

◆ mi_new_nothrow()

+ +
+
+ + + + + + + + +
void* mi_new_nothrow (size_t n)
+
+ +

return NULL on failure.

diff --git a/docs/group__posix.js b/docs/group__posix.js index 300d7585..5584092b 100644 --- a/docs/group__posix.js +++ b/docs/group__posix.js @@ -11,6 +11,8 @@ var group__posix = [ "mi_memalign", "group__posix.html#gaab7fa71ea93b96873f5d9883db57d40e", null ], [ "mi_new", "group__posix.html#gaad048a9fce3d02c5909cd05c6ec24545", null ], [ "mi_new_aligned", "group__posix.html#gaef2c2bdb4f70857902d3c8903ac095f3", null ], + [ "mi_new_aligned_nothrow", "group__posix.html#gab5e29558926d934c3f1cae8c815f942c", null ], + [ "mi_new_nothrow", "group__posix.html#gaeaded64eda71ed6b1d569d3e723abc4a", null ], [ "mi_posix_memalign", "group__posix.html#gacff84f226ba9feb2031b8992e5579447", null ], [ "mi_pvalloc", "group__posix.html#gaeb325c39b887d3b90d85d1eb1712fb1e", null ], [ "mi_reallocarray", "group__posix.html#ga48fad8648a2f1dab9c87ea9448a52088", null ], diff --git a/docs/mimalloc-doc_8h_source.html b/docs/mimalloc-doc_8h_source.html index f12cfdb4..b4b6e01d 100644 --- a/docs/mimalloc-doc_8h_source.html +++ b/docs/mimalloc-doc_8h_source.html @@ -102,9 +102,10 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mimalloc-doc.h
-
1 /* ----------------------------------------------------------------------------
2 Copyright (c) 2018, Microsoft Research, Daan Leijen
3 This is free software; you can redistribute it and/or modify it under the
4 terms of the MIT license. A copy of the license can be found in the file
5 "LICENSE" at the root of this distribution.
6 -----------------------------------------------------------------------------*/
7 
8 #error "documentation file only!"
9 
10 
78 
82 
86 void mi_free(void* p);
87 
92 void* mi_malloc(size_t size);
93 
98 void* mi_zalloc(size_t size);
99 
109 void* mi_calloc(size_t count, size_t size);
110 
123 void* mi_realloc(void* p, size_t newsize);
124 
135 void* mi_recalloc(void* p, size_t count, size_t size);
136 
150 void* mi_expand(void* p, size_t newsize);
151 
161 void* mi_mallocn(size_t count, size_t size);
162 
172 void* mi_reallocn(void* p, size_t count, size_t size);
173 
190 void* mi_reallocf(void* p, size_t newsize);
191 
192 
201 char* mi_strdup(const char* s);
202 
212 char* mi_strndup(const char* s, size_t n);
213 
226 char* mi_realpath(const char* fname, char* resolved_name);
227 
229 
230 // ------------------------------------------------------
231 // Extended functionality
232 // ------------------------------------------------------
233 
237 
240 #define MI_SMALL_SIZE_MAX (128*sizeof(void*))
241 
249 void* mi_malloc_small(size_t size);
250 
258 void* mi_zalloc_small(size_t size);
259 
274 size_t mi_usable_size(void* p);
275 
285 size_t mi_good_size(size_t size);
286 
294 void mi_collect(bool force);
295 
300 void mi_stats_print(FILE* out);
301 
303 void mi_stats_reset();
304 
308 void mi_thread_init();
309 
314 void mi_thread_done();
315 
320 void mi_thread_stats_print(FILE* out);
321 
327 typedef void (mi_deferred_free_fun)(bool force, unsigned long long heartbeat);
328 
343 void mi_register_deferred_free(mi_deferred_free_fun* deferred_free);
344 
346 
347 // ------------------------------------------------------
348 // Aligned allocation
349 // ------------------------------------------------------
350 
356 
369 void* mi_malloc_aligned(size_t size, size_t alignment);
370 void* mi_zalloc_aligned(size_t size, size_t alignment);
371 void* mi_calloc_aligned(size_t count, size_t size, size_t alignment);
372 void* mi_realloc_aligned(void* p, size_t newsize, size_t alignment);
373 
384 void* mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset);
385 void* mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset);
386 void* mi_calloc_aligned_at(size_t count, size_t size, size_t alignment, size_t offset);
387 void* mi_realloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);
388 
390 
396 
401 struct mi_heap_s;
402 
407 typedef struct mi_heap_s mi_heap_t;
408 
410 mi_heap_t* mi_heap_new();
411 
419 void mi_heap_delete(mi_heap_t* heap);
420 
428 void mi_heap_destroy(mi_heap_t* heap);
429 
433 mi_heap_t* mi_heap_set_default(mi_heap_t* heap);
434 
437 mi_heap_t* mi_heap_get_default();
438 
444 mi_heap_t* mi_heap_get_backing();
445 
448 void* mi_heap_malloc(mi_heap_t* heap, size_t size);
449 
452 void* mi_heap_zalloc(mi_heap_t* heap, size_t size);
453 
456 void* mi_heap_calloc(mi_heap_t* heap, size_t count, size_t size);
457 
460 void* mi_heap_mallocn(mi_heap_t* heap, size_t count, size_t size);
461 
464 char* mi_heap_strdup(mi_heap_t* heap, const char* s);
465 
468 char* mi_heap_strndup(mi_heap_t* heap, const char* s, size_t n);
469 
472 char* mi_heap_realpath(mi_heap_t* heap, const char* fname, char* resolved_name);
473 
474 void* mi_heap_realloc(mi_heap_t* heap, void* p, size_t newsize);
475 void* mi_heap_reallocn(mi_heap_t* heap, void* p, size_t count, size_t size);
476 void* mi_heap_reallocf(mi_heap_t* heap, void* p, size_t newsize);
477 
478 void* mi_heap_malloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
479 void* mi_heap_malloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
480 void* mi_heap_zalloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
481 void* mi_heap_zalloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
482 void* mi_heap_calloc_aligned(mi_heap_t* heap, size_t count, size_t size, size_t alignment);
483 void* mi_heap_calloc_aligned_at(mi_heap_t* heap, size_t count, size_t size, size_t alignment, size_t offset);
484 void* mi_heap_realloc_aligned(mi_heap_t* heap, void* p, size_t newsize, size_t alignment);
485 void* mi_heap_realloc_aligned_at(mi_heap_t* heap, void* p, size_t newsize, size_t alignment, size_t offset);
486 
488 
494 
506 #define mi_malloc_tp(tp) ((tp*)mi_malloc(sizeof(tp)))
507 
509 #define mi_zalloc_tp(tp) ((tp*)mi_zalloc(sizeof(tp)))
510 
512 #define mi_calloc_tp(tp,count) ((tp*)mi_calloc(count,sizeof(tp)))
513 
515 #define mi_mallocn_tp(tp,count) ((tp*)mi_mallocn(count,sizeof(tp)))
516 
518 #define mi_reallocn_tp(p,tp,count) ((tp*)mi_reallocn(p,count,sizeof(tp)))
519 
521 #define mi_heap_malloc_tp(hp,tp) ((tp*)mi_heap_malloc(hp,sizeof(tp)))
522 
524 #define mi_heap_zalloc_tp(hp,tp) ((tp*)mi_heap_zalloc(hp,sizeof(tp)))
525 
527 #define mi_heap_calloc_tp(hp,tp,count) ((tp*)mi_heap_calloc(hp,count,sizeof(tp)))
528 
530 #define mi_heap_mallocn_tp(hp,tp,count) ((tp*)mi_heap_mallocn(hp,count,sizeof(tp)))
531 
533 #define mi_heap_reallocn_tp(hp,p,tp,count) ((tp*)mi_heap_reallocn(p,count,sizeof(tp)))
534 
536 
542 
549 bool mi_heap_contains_block(mi_heap_t* heap, const void* p);
550 
559 bool mi_heap_check_owned(mi_heap_t* heap, const void* p);
560 
568 bool mi_check_owned(const void* p);
569 
572 typedef struct mi_heap_area_s {
573  void* blocks;
574  size_t reserved;
575  size_t committed;
576  size_t used;
577  size_t block_size;
578 } mi_heap_area_t;
579 
587 typedef bool (mi_block_visit_fun)(const mi_heap_t* heap, const mi_heap_area_t* area, void* block, size_t block_size, void* arg);
588 
600 bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_all_blocks, mi_block_visit_fun* visitor, void* arg);
601 
603 
609 
611 typedef enum mi_option_e {
612  mi_option_page_reset,
613  mi_option_cache_reset,
614  mi_option_pool_commit,
615  mi_option_show_stats,
616  mi_option_show_errors,
617  mi_option_verbose,
618  _mi_option_last
619 } mi_option_t;
620 
621 bool mi_option_enabled(mi_option_t option);
622 void mi_option_enable(mi_option_t option, bool enable);
623 void mi_option_enable_default(mi_option_t option, bool enable);
624 
625 long mi_option_get(mi_option_t option);
626 void mi_option_set(mi_option_t option, long value);
627 void mi_option_set_default(mi_option_t option, long value);
628 
629 
631 
638 
639 void* mi_recalloc(void* p, size_t count, size_t size);
640 size_t mi_malloc_size(const void* p);
641 size_t mi_malloc_usable_size(const void *p);
642 void mi_cfree(void* p);
643 
644 int mi_posix_memalign(void** p, size_t alignment, size_t size);
645 int mi__posix_memalign(void** p, size_t alignment, size_t size);
646 void* mi_memalign(size_t alignment, size_t size);
647 void* mi_valloc(size_t size);
648 
649 void* mi_pvalloc(size_t size);
650 void* mi_aligned_alloc(size_t alignment, size_t size);
651 void* mi_reallocarray(void* p, size_t count, size_t size);
652 
653 void mi_free_size(void* p, size_t size);
654 void mi_free_size_aligned(void* p, size_t size, size_t alignment);
655 void mi_free_aligned(void* p, size_t alignment);
656 
658 void* mi_new(std::size_t n) noexcept(false);
659 
661 void* mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false);
662 
663 
665 
mi_stats_print
void mi_stats_print(FILE *out)
Print statistics.
+
1 /* ----------------------------------------------------------------------------
2 Copyright (c) 2018, Microsoft Research, Daan Leijen
3 This is free software; you can redistribute it and/or modify it under the
4 terms of the MIT license. A copy of the license can be found in the file
5 "LICENSE" at the root of this distribution.
6 -----------------------------------------------------------------------------*/
7 
8 #error "documentation file only!"
9 
10 
78 
82 
86 void mi_free(void* p);
87 
92 void* mi_malloc(size_t size);
93 
98 void* mi_zalloc(size_t size);
99 
109 void* mi_calloc(size_t count, size_t size);
110 
123 void* mi_realloc(void* p, size_t newsize);
124 
135 void* mi_recalloc(void* p, size_t count, size_t size);
136 
150 void* mi_expand(void* p, size_t newsize);
151 
161 void* mi_mallocn(size_t count, size_t size);
162 
172 void* mi_reallocn(void* p, size_t count, size_t size);
173 
190 void* mi_reallocf(void* p, size_t newsize);
191 
192 
201 char* mi_strdup(const char* s);
202 
212 char* mi_strndup(const char* s, size_t n);
213 
226 char* mi_realpath(const char* fname, char* resolved_name);
227 
229 
230 // ------------------------------------------------------
231 // Extended functionality
232 // ------------------------------------------------------
233 
237 
240 #define MI_SMALL_SIZE_MAX (128*sizeof(void*))
241 
249 void* mi_malloc_small(size_t size);
250 
258 void* mi_zalloc_small(size_t size);
259 
274 size_t mi_usable_size(void* p);
275 
285 size_t mi_good_size(size_t size);
286 
294 void mi_collect(bool force);
295 
300 void mi_stats_print(FILE* out);
301 
303 void mi_stats_reset();
304 
308 void mi_thread_init();
309 
314 void mi_thread_done();
315 
320 void mi_thread_stats_print(FILE* out);
321 
327 typedef void (mi_deferred_free_fun)(bool force, unsigned long long heartbeat);
328 
343 void mi_register_deferred_free(mi_deferred_free_fun* deferred_free);
344 
346 
347 // ------------------------------------------------------
348 // Aligned allocation
349 // ------------------------------------------------------
350 
356 
369 void* mi_malloc_aligned(size_t size, size_t alignment);
370 void* mi_zalloc_aligned(size_t size, size_t alignment);
371 void* mi_calloc_aligned(size_t count, size_t size, size_t alignment);
372 void* mi_realloc_aligned(void* p, size_t newsize, size_t alignment);
373 
384 void* mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset);
385 void* mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset);
386 void* mi_calloc_aligned_at(size_t count, size_t size, size_t alignment, size_t offset);
387 void* mi_realloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);
388 
390 
396 
401 struct mi_heap_s;
402 
407 typedef struct mi_heap_s mi_heap_t;
408 
410 mi_heap_t* mi_heap_new();
411 
419 void mi_heap_delete(mi_heap_t* heap);
420 
428 void mi_heap_destroy(mi_heap_t* heap);
429 
433 mi_heap_t* mi_heap_set_default(mi_heap_t* heap);
434 
437 mi_heap_t* mi_heap_get_default();
438 
444 mi_heap_t* mi_heap_get_backing();
445 
448 void* mi_heap_malloc(mi_heap_t* heap, size_t size);
449 
452 void* mi_heap_zalloc(mi_heap_t* heap, size_t size);
453 
456 void* mi_heap_calloc(mi_heap_t* heap, size_t count, size_t size);
457 
460 void* mi_heap_mallocn(mi_heap_t* heap, size_t count, size_t size);
461 
464 char* mi_heap_strdup(mi_heap_t* heap, const char* s);
465 
468 char* mi_heap_strndup(mi_heap_t* heap, const char* s, size_t n);
469 
472 char* mi_heap_realpath(mi_heap_t* heap, const char* fname, char* resolved_name);
473 
474 void* mi_heap_realloc(mi_heap_t* heap, void* p, size_t newsize);
475 void* mi_heap_reallocn(mi_heap_t* heap, void* p, size_t count, size_t size);
476 void* mi_heap_reallocf(mi_heap_t* heap, void* p, size_t newsize);
477 
478 void* mi_heap_malloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
479 void* mi_heap_malloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
480 void* mi_heap_zalloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
481 void* mi_heap_zalloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
482 void* mi_heap_calloc_aligned(mi_heap_t* heap, size_t count, size_t size, size_t alignment);
483 void* mi_heap_calloc_aligned_at(mi_heap_t* heap, size_t count, size_t size, size_t alignment, size_t offset);
484 void* mi_heap_realloc_aligned(mi_heap_t* heap, void* p, size_t newsize, size_t alignment);
485 void* mi_heap_realloc_aligned_at(mi_heap_t* heap, void* p, size_t newsize, size_t alignment, size_t offset);
486 
488 
494 
506 #define mi_malloc_tp(tp) ((tp*)mi_malloc(sizeof(tp)))
507 
509 #define mi_zalloc_tp(tp) ((tp*)mi_zalloc(sizeof(tp)))
510 
512 #define mi_calloc_tp(tp,count) ((tp*)mi_calloc(count,sizeof(tp)))
513 
515 #define mi_mallocn_tp(tp,count) ((tp*)mi_mallocn(count,sizeof(tp)))
516 
518 #define mi_reallocn_tp(p,tp,count) ((tp*)mi_reallocn(p,count,sizeof(tp)))
519 
521 #define mi_heap_malloc_tp(hp,tp) ((tp*)mi_heap_malloc(hp,sizeof(tp)))
522 
524 #define mi_heap_zalloc_tp(hp,tp) ((tp*)mi_heap_zalloc(hp,sizeof(tp)))
525 
527 #define mi_heap_calloc_tp(hp,tp,count) ((tp*)mi_heap_calloc(hp,count,sizeof(tp)))
528 
530 #define mi_heap_mallocn_tp(hp,tp,count) ((tp*)mi_heap_mallocn(hp,count,sizeof(tp)))
531 
533 #define mi_heap_reallocn_tp(hp,p,tp,count) ((tp*)mi_heap_reallocn(p,count,sizeof(tp)))
534 
536 
542 
549 bool mi_heap_contains_block(mi_heap_t* heap, const void* p);
550 
559 bool mi_heap_check_owned(mi_heap_t* heap, const void* p);
560 
568 bool mi_check_owned(const void* p);
569 
572 typedef struct mi_heap_area_s {
573  void* blocks;
574  size_t reserved;
575  size_t committed;
576  size_t used;
577  size_t block_size;
578 } mi_heap_area_t;
579 
587 typedef bool (mi_block_visit_fun)(const mi_heap_t* heap, const mi_heap_area_t* area, void* block, size_t block_size, void* arg);
588 
600 bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_all_blocks, mi_block_visit_fun* visitor, void* arg);
601 
603 
609 
611 typedef enum mi_option_e {
612  // stable options
613  mi_option_show_stats,
614  mi_option_show_errors,
615  mi_option_verbose,
616  // the following options are experimental
617  mi_option_secure,
618  mi_option_eager_commit,
619  mi_option_eager_region_commit,
620  mi_option_large_os_pages,
621  mi_option_page_reset,
622  mi_option_cache_reset,
623  mi_option_reset_decommits,
624  mi_option_reset_discards,
625  _mi_option_last
626 } mi_option_t;
627 
628 
629 bool mi_option_enabled(mi_option_t option);
630 void mi_option_enable(mi_option_t option, bool enable);
631 void mi_option_enable_default(mi_option_t option, bool enable);
632 
633 long mi_option_get(mi_option_t option);
634 void mi_option_set(mi_option_t option, long value);
635 void mi_option_set_default(mi_option_t option, long value);
636 
637 
639 
646 
647 void* mi_recalloc(void* p, size_t count, size_t size);
648 size_t mi_malloc_size(const void* p);
649 size_t mi_malloc_usable_size(const void *p);
650 void mi_cfree(void* p);
651 
652 int mi_posix_memalign(void** p, size_t alignment, size_t size);
653 int mi__posix_memalign(void** p, size_t alignment, size_t size);
654 void* mi_memalign(size_t alignment, size_t size);
655 void* mi_valloc(size_t size);
656 
657 void* mi_pvalloc(size_t size);
658 void* mi_aligned_alloc(size_t alignment, size_t size);
659 void* mi_reallocarray(void* p, size_t count, size_t size);
660 
661 void mi_free_size(void* p, size_t size);
662 void mi_free_size_aligned(void* p, size_t size, size_t alignment);
663 void mi_free_aligned(void* p, size_t alignment);
664 
666 void* mi_new(std::size_t n) noexcept(false);
667 
669 void* mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false);
670 
672 void* mi_new_nothrow(size_t n);
673 ``
675 void* mi_new_aligned_nothrow(size_t n, size_t alignment);
676 
678 
mi_stats_print
void mi_stats_print(FILE *out)
Print statistics.
mi_option_enable_default
void mi_option_enable_default(mi_option_t option, bool enable)
mi_usable_size
size_t mi_usable_size(void *p)
Return the available bytes in a memory block.
+
mi_option_reset_discards
Experimental.
Definition: mimalloc-doc.h:624
mi_reallocn
void * mi_reallocn(void *p, size_t count, size_t size)
Re-allocate memory to count elements of size bytes.
mi_malloc_aligned
void * mi_malloc_aligned(size_t size, size_t alignment)
Allocate size bytes aligned by alignment.
mi_heap_realloc_aligned
void * mi_heap_realloc_aligned(mi_heap_t *heap, void *p, size_t newsize, size_t alignment)
@@ -112,17 +113,18 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mi_mallocn
void * mi_mallocn(size_t count, size_t size)
Allocate count elements of size bytes.
mi_malloc_size
size_t mi_malloc_size(const void *p)
mi_thread_done
void mi_thread_done()
Uninitialize mimalloc on a thread.
-
mi_option_cache_reset
Reset segment memory when a segment is cached.
Definition: mimalloc-doc.h:613
+
mi_option_cache_reset
Reset segment memory when a segment is cached.
Definition: mimalloc-doc.h:622
mi_posix_memalign
int mi_posix_memalign(void **p, size_t alignment, size_t size)
-
mi_option_pool_commit
Commit segments in large pools.
Definition: mimalloc-doc.h:614
mi_option_set_default
void mi_option_set_default(mi_option_t option, long value)
-
mi_new_aligned
void * mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false)
Only defined in C++ compilation; raise std::bad_alloc exception on failure.
+
mi_new_aligned
void * mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false)
raise std::bad_alloc exception on failure.
+
mi_option_eager_commit
Eagerly commit segments (4MiB) (enabled by default).
Definition: mimalloc-doc.h:618
mi_heap_zalloc
void * mi_heap_zalloc(mi_heap_t *heap, size_t size)
Allocate zero-initialized in a specific heap.
mi_option_set
void mi_option_set(mi_option_t option, long value)
mi_register_deferred_free
void mi_register_deferred_free(mi_deferred_free_fun *deferred_free)
Register a deferred free function.
+
mi_option_eager_region_commit
Eagerly commit large (256MiB) memory regions (enabled by default except on Windows)
Definition: mimalloc-doc.h:619
mi_cfree
void mi_cfree(void *p)
mi_thread_stats_print
void mi_thread_stats_print(FILE *out)
Print out heap statistics for this thread.
-
_mi_option_last
Definition: mimalloc-doc.h:618
+
_mi_option_last
Definition: mimalloc-doc.h:625
mi_realloc_aligned_at
void * mi_realloc_aligned_at(void *p, size_t newsize, size_t alignment, size_t offset)
mi_heap_area_t::blocks
void * blocks
start of the area containing heap blocks
Definition: mimalloc-doc.h:573
mi_realloc_aligned
void * mi_realloc_aligned(void *p, size_t newsize, size_t alignment)
@@ -140,7 +142,7 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mi_zalloc
void * mi_zalloc(size_t size)
Allocate zero-initialized size bytes.
mi_thread_init
void mi_thread_init()
Initialize mimalloc on a thread.
mi_heap_calloc
void * mi_heap_calloc(mi_heap_t *heap, size_t count, size_t size)
Allocate count zero-initialized elements in a specific heap.
-
mi_new
void * mi_new(std::size_t n) noexcept(false)
Only defined in C++ compilation; raise std::bad_alloc exception on failure.
+
mi_new
void * mi_new(std::size_t n) noexcept(false)
raise std::bad_alloc exception on failure.
mi_heap_calloc_aligned
void * mi_heap_calloc_aligned(mi_heap_t *heap, size_t count, size_t size, size_t alignment)
mi_heap_area_t::block_size
size_t block_size
size in bytes of one block
Definition: mimalloc-doc.h:577
mi_reallocarray
void * mi_reallocarray(void *p, size_t count, size_t size)
@@ -148,18 +150,21 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mi_realloc
void * mi_realloc(void *p, size_t newsize)
Re-allocate memory to newsize bytes.
mi_heap_reallocf
void * mi_heap_reallocf(mi_heap_t *heap, void *p, size_t newsize)
mi_free_size_aligned
void mi_free_size_aligned(void *p, size_t size, size_t alignment)
-
mi_option_page_reset
Reset page memory when it becomes free.
Definition: mimalloc-doc.h:612
+
mi_option_page_reset
Reset page memory when it becomes free.
Definition: mimalloc-doc.h:621
mi_heap_visit_blocks
bool mi_heap_visit_blocks(const mi_heap_t *heap, bool visit_all_blocks, mi_block_visit_fun *visitor, void *arg)
Visit all areas and blocks in a heap.
mi_malloc
void * mi_malloc(size_t size)
Allocate size bytes.
mi_option_enabled
bool mi_option_enabled(mi_option_t option)
+
mi_option_reset_decommits
Experimental.
Definition: mimalloc-doc.h:623
mi_heap_strndup
char * mi_heap_strndup(mi_heap_t *heap, const char *s, size_t n)
Duplicate a string of at most length n in a specific heap.
mi_block_visit_fun
bool() mi_block_visit_fun(const mi_heap_t *heap, const mi_heap_area_t *area, void *block, size_t block_size, void *arg)
Visitor function passed to mi_heap_visit_blocks()
Definition: mimalloc-doc.h:587
mi_heap_malloc_aligned_at
void * mi_heap_malloc_aligned_at(mi_heap_t *heap, size_t size, size_t alignment, size_t offset)
mi_realpath
char * mi_realpath(const char *fname, char *resolved_name)
Resolve a file path name.
-
mi_option_show_errors
Print error messages to stderr.
Definition: mimalloc-doc.h:616
+
mi_option_show_errors
Print error messages to stderr.
Definition: mimalloc-doc.h:614
mi_memalign
void * mi_memalign(size_t alignment, size_t size)
+
mi_new_aligned_nothrow
void * mi_new_aligned_nothrow(size_t n, size_t alignment)
return NULL on failure.
+
mi_new_nothrow
void * mi_new_nothrow(size_t n)
return NULL on failure.
mi_heap_contains_block
bool mi_heap_contains_block(mi_heap_t *heap, const void *p)
Does a heap contain a pointer to a previously allocated block?
-
mi_option_verbose
Print verbose messages to stderr.
Definition: mimalloc-doc.h:617
+
mi_option_verbose
Print verbose messages to stderr.
Definition: mimalloc-doc.h:615
mi_zalloc_aligned_at
void * mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset)
mi_malloc_aligned_at
void * mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset)
Allocate size bytes aligned by alignment at a specified offset.
mi_heap_delete
void mi_heap_delete(mi_heap_t *heap)
Delete a previously allocated heap.
@@ -169,7 +174,7 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mi_good_size
size_t mi_good_size(size_t size)
Return the used allocation size.
mi_heap_mallocn
void * mi_heap_mallocn(mi_heap_t *heap, size_t count, size_t size)
Allocate count elements in a specific heap.
mi_heap_area_t
An area of heap space contains blocks of a single size.
Definition: mimalloc-doc.h:572
-
mi_option_show_stats
Print statistics to stderr when the program is done.
Definition: mimalloc-doc.h:615
+
mi_option_show_stats
Print statistics to stderr when the program is done.
Definition: mimalloc-doc.h:613
mi_zalloc_aligned
void * mi_zalloc_aligned(size_t size, size_t alignment)
mi_heap_area_t::reserved
size_t reserved
bytes reserved for this area
Definition: mimalloc-doc.h:574
mi_heap_t
struct mi_heap_s mi_heap_t
Type of first-class heaps.
Definition: mimalloc-doc.h:407
@@ -179,6 +184,8 @@ $(document).ready(function(){initNavTree('mimalloc-doc_8h_source.html','');});
mi_collect
void mi_collect(bool force)
Eagerly free memory.
mi_heap_destroy
void mi_heap_destroy(mi_heap_t *heap)
Destroy a heap, freeing all its still allocated blocks.
mi_calloc_aligned_at
void * mi_calloc_aligned_at(size_t count, size_t size, size_t alignment, size_t offset)
+
mi_option_large_os_pages
Use large OS pages if possible.
Definition: mimalloc-doc.h:620
+
mi_option_secure
Experimental.
Definition: mimalloc-doc.h:617
mi_stats_reset
void mi_stats_reset()
Reset statistics.
mi_heap_reallocn
void * mi_heap_reallocn(mi_heap_t *heap, void *p, size_t count, size_t size)
mi_heap_realloc
void * mi_heap_realloc(mi_heap_t *heap, void *p, size_t newsize)
diff --git a/docs/navtreeindex0.js b/docs/navtreeindex0.js index 2cc6d486..f026a1ff 100644 --- a/docs/navtreeindex0.js +++ b/docs/navtreeindex0.js @@ -89,28 +89,35 @@ var NAVTREEINDEX0 = "group__options.html#gacebe3f6d91b4a50b54eb84e2a1da1b30":[4,6,3], "group__options.html#gaf84921c32375e25754dc2ee6a911fa60":[4,6,5], "group__options.html#gafebf7ed116adb38ae5218bc3ce06884c":[4,6,0], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca0957ef73b2550764b4840edf48422fda":[4,6,0,3], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1d7948dd9565c26d411e6dbdf549be79":[4,6,0,2], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca5b4357b74be0d87568036c32eb1a2e4a":[4,6,0,6], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca7c8b7bf5281c581bad64f5daa6442777":[4,6,0,5], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07":[4,6,0,1], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968":[4,6,0,0], -"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cafbf4822e5c00732c5984b32a032837f0":[4,6,0,4], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca083ee20765063fc6d727e11d33cf378f":[4,6,0,3], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca0957ef73b2550764b4840edf48422fda":[4,6,0,0], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1e8de72c93da7ff22d91e1e27b52ac2b":[4,6,0,4], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca32ce97ece29f69e82579679cf8a307ad":[4,6,0,5], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca4192d491200d0055df0554d4cf65054e":[4,6,0,6], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca5b4357b74be0d87568036c32eb1a2e4a":[4,6,0,11], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca7c8b7bf5281c581bad64f5daa6442777":[4,6,0,2], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cab3a837b5ceee250e14e051dbee2a441b":[4,6,0,10], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07":[4,6,0,8], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac81ee965b130fa81238913a3c239d536":[4,6,0,9], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968":[4,6,0,7], +"group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cafbf4822e5c00732c5984b32a032837f0":[4,6,0,1], "group__posix.html":[4,7], "group__posix.html#ga06d07cf357bbac5c73ba5d0c0c421e17":[4,7,7], "group__posix.html#ga0d28d5cf61e6bfbb18c63092939fe5c9":[4,7,3], "group__posix.html#ga1326d2e4388630b5f81ca7206318b8e5":[4,7,1], "group__posix.html#ga4531c9e775bb3ae12db57c1ba8a5d7de":[4,7,6], -"group__posix.html#ga48fad8648a2f1dab9c87ea9448a52088":[4,7,13], +"group__posix.html#ga48fad8648a2f1dab9c87ea9448a52088":[4,7,15], "group__posix.html#ga705dc7a64bffacfeeb0141501a5c35d7":[4,7,2], "group__posix.html#ga72e9d7ffb5fe94d69bc722c8506e27bc":[4,7,5], -"group__posix.html#ga73baaf5951f5165ba0763d0c06b6a93b":[4,7,14], +"group__posix.html#ga73baaf5951f5165ba0763d0c06b6a93b":[4,7,16], "group__posix.html#gaab7fa71ea93b96873f5d9883db57d40e":[4,7,8], "group__posix.html#gaad048a9fce3d02c5909cd05c6ec24545":[4,7,9], -"group__posix.html#gacff84f226ba9feb2031b8992e5579447":[4,7,11], +"group__posix.html#gab5e29558926d934c3f1cae8c815f942c":[4,7,11], +"group__posix.html#gacff84f226ba9feb2031b8992e5579447":[4,7,13], "group__posix.html#gad5a69c8fea96aa2b7a7c818c2130090a":[4,7,0], "group__posix.html#gae01389eedab8d67341ff52e2aad80ebb":[4,7,4], -"group__posix.html#gaeb325c39b887d3b90d85d1eb1712fb1e":[4,7,12], +"group__posix.html#gaeaded64eda71ed6b1d569d3e723abc4a":[4,7,12], +"group__posix.html#gaeb325c39b887d3b90d85d1eb1712fb1e":[4,7,14], "group__posix.html#gaef2c2bdb4f70857902d3c8903ac095f3":[4,7,10], "group__typed.html":[4,4], "group__typed.html#ga0619a62c5fd886f1016030abe91f0557":[4,4,6], diff --git a/docs/overrides.html b/docs/overrides.html index 2360a936..2833f4f9 100644 --- a/docs/overrides.html +++ b/docs/overrides.html @@ -105,17 +105,22 @@ $(document).ready(function(){initNavTree('overrides.html','');});

Overriding the standard malloc can be done either dynamically or statically.

Dynamic override

This is the recommended way to override the standard malloc interface.

-

Unix, BSD, macOS

+

Linux, BSD

On these systems we preload the mimalloc shared library so all calls to the standard malloc interface are resolved to the mimalloc library.

    -
  • env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram (on Linux, BSD, etc.)
    • -

  • env DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram (On macOS)

    -

    Note certain security restrictions may apply when doing this from the shell.

    -
    • +
  • env LD_PRELOAD=/usr/lib/libmimalloc.so myprogram
-

You can set extra environment variables to check that mimalloc is running, like:

env MIMALLOC_VERBOSE=1 LD_PRELOAD=/usr/lib/libmimalloc.so myprogram

or run with the debug version to get detailed statistics:

env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram

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 call to the mimalloc API in the main function, like mi_version().

+

You can set extra environment variables to check that mimalloc is running, like:

env MIMALLOC_VERBOSE=1 LD_PRELOAD=/usr/lib/libmimalloc.so myprogram

or run with the debug version to get detailed statistics:

env MIMALLOC_SHOW_STATS=1 LD_PRELOAD=/usr/lib/libmimalloc-debug.so myprogram

MacOS

+

On macOS we can also preload the mimalloc shared library so all calls to the standard malloc interface are resolved to the mimalloc library.

+
    +
  • env DYLD_FORCE_FLAT_NAMESPACE=1 DYLD_INSERT_LIBRARIES=/usr/lib/libmimalloc.dylib myprogram
    • +
+

Note that certain security restrictions may apply when doing this from the shell.

+

Note: unfortunately, at this time, dynamic overriding on macOS seems broken but it is actively worked on to fix this (see issue #50).

+

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 call to the mimalloc API in the main function, like mi_version() (or use the /INCLUDE:mi_version switch on the linker)

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.

+

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.

Static override

On Unix systems, you can also statically link with mimalloc to override the standard malloc interface. The recommended way is to link the final program with the mimalloc single object file (mimalloc-override.o). We use an object file instead of a library file as linkers give preference to that over archives to resolve symbols. To ensure that the standard malloc interface resolves to the mimalloc library, link it as the first object file. For example:

gcc -o myprogram mimalloc-override.o myfile1.c ...

List of Overrides:

diff --git a/docs/search/all_6.js b/docs/search/all_6.js index cb826ae7..58ffa7e6 100644 --- a/docs/search/all_6.js +++ b/docs/search/all_6.js @@ -63,13 +63,20 @@ var searchData= ['mi_5fmemalign',['mi_memalign',['../group__posix.html#gaab7fa71ea93b96873f5d9883db57d40e',1,'mimalloc-doc.h']]], ['mi_5fnew',['mi_new',['../group__posix.html#gaad048a9fce3d02c5909cd05c6ec24545',1,'mimalloc-doc.h']]], ['mi_5fnew_5faligned',['mi_new_aligned',['../group__posix.html#gaef2c2bdb4f70857902d3c8903ac095f3',1,'mimalloc-doc.h']]], + ['mi_5fnew_5faligned_5fnothrow',['mi_new_aligned_nothrow',['../group__posix.html#gab5e29558926d934c3f1cae8c815f942c',1,'mimalloc-doc.h']]], + ['mi_5fnew_5fnothrow',['mi_new_nothrow',['../group__posix.html#gaeaded64eda71ed6b1d569d3e723abc4a',1,'mimalloc-doc.h']]], ['mi_5foption_5fcache_5freset',['mi_option_cache_reset',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07',1,'mimalloc-doc.h']]], + ['mi_5foption_5feager_5fcommit',['mi_option_eager_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1e8de72c93da7ff22d91e1e27b52ac2b',1,'mimalloc-doc.h']]], + ['mi_5foption_5feager_5fregion_5fcommit',['mi_option_eager_region_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca32ce97ece29f69e82579679cf8a307ad',1,'mimalloc-doc.h']]], ['mi_5foption_5fenable',['mi_option_enable',['../group__options.html#ga6d45a20a3131f18bc351b69763b38ce4',1,'mimalloc-doc.h']]], ['mi_5foption_5fenable_5fdefault',['mi_option_enable_default',['../group__options.html#ga37988264b915a7db92530cc02d5494cb',1,'mimalloc-doc.h']]], ['mi_5foption_5fenabled',['mi_option_enabled',['../group__options.html#gacebe3f6d91b4a50b54eb84e2a1da1b30',1,'mimalloc-doc.h']]], ['mi_5foption_5fget',['mi_option_get',['../group__options.html#ga7e8af195cc81d3fa64ccf2662caa565a',1,'mimalloc-doc.h']]], + ['mi_5foption_5flarge_5fos_5fpages',['mi_option_large_os_pages',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca4192d491200d0055df0554d4cf65054e',1,'mimalloc-doc.h']]], ['mi_5foption_5fpage_5freset',['mi_option_page_reset',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968',1,'mimalloc-doc.h']]], - ['mi_5foption_5fpool_5fcommit',['mi_option_pool_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1d7948dd9565c26d411e6dbdf549be79',1,'mimalloc-doc.h']]], + ['mi_5foption_5freset_5fdecommits',['mi_option_reset_decommits',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac81ee965b130fa81238913a3c239d536',1,'mimalloc-doc.h']]], + ['mi_5foption_5freset_5fdiscards',['mi_option_reset_discards',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cab3a837b5ceee250e14e051dbee2a441b',1,'mimalloc-doc.h']]], + ['mi_5foption_5fsecure',['mi_option_secure',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca083ee20765063fc6d727e11d33cf378f',1,'mimalloc-doc.h']]], ['mi_5foption_5fset',['mi_option_set',['../group__options.html#gaf84921c32375e25754dc2ee6a911fa60',1,'mimalloc-doc.h']]], ['mi_5foption_5fset_5fdefault',['mi_option_set_default',['../group__options.html#ga7ef623e440e6e5545cb08c94e71e4b90',1,'mimalloc-doc.h']]], ['mi_5foption_5fshow_5ferrors',['mi_option_show_errors',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cafbf4822e5c00732c5984b32a032837f0',1,'mimalloc-doc.h']]], diff --git a/docs/search/enumvalues_1.js b/docs/search/enumvalues_1.js index 2dacbec8..b9c9b6f6 100644 --- a/docs/search/enumvalues_1.js +++ b/docs/search/enumvalues_1.js @@ -1,8 +1,13 @@ var searchData= [ ['mi_5foption_5fcache_5freset',['mi_option_cache_reset',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac2157a0cb79cd996c1db7d9f6a090c07',1,'mimalloc-doc.h']]], + ['mi_5foption_5feager_5fcommit',['mi_option_eager_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1e8de72c93da7ff22d91e1e27b52ac2b',1,'mimalloc-doc.h']]], + ['mi_5foption_5feager_5fregion_5fcommit',['mi_option_eager_region_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca32ce97ece29f69e82579679cf8a307ad',1,'mimalloc-doc.h']]], + ['mi_5foption_5flarge_5fos_5fpages',['mi_option_large_os_pages',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca4192d491200d0055df0554d4cf65054e',1,'mimalloc-doc.h']]], ['mi_5foption_5fpage_5freset',['mi_option_page_reset',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cada854dd272c66342f18a93ee254a2968',1,'mimalloc-doc.h']]], - ['mi_5foption_5fpool_5fcommit',['mi_option_pool_commit',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca1d7948dd9565c26d411e6dbdf549be79',1,'mimalloc-doc.h']]], + ['mi_5foption_5freset_5fdecommits',['mi_option_reset_decommits',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cac81ee965b130fa81238913a3c239d536',1,'mimalloc-doc.h']]], + ['mi_5foption_5freset_5fdiscards',['mi_option_reset_discards',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cab3a837b5ceee250e14e051dbee2a441b',1,'mimalloc-doc.h']]], + ['mi_5foption_5fsecure',['mi_option_secure',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca083ee20765063fc6d727e11d33cf378f',1,'mimalloc-doc.h']]], ['mi_5foption_5fshow_5ferrors',['mi_option_show_errors',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884cafbf4822e5c00732c5984b32a032837f0',1,'mimalloc-doc.h']]], ['mi_5foption_5fshow_5fstats',['mi_option_show_stats',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca0957ef73b2550764b4840edf48422fda',1,'mimalloc-doc.h']]], ['mi_5foption_5fverbose',['mi_option_verbose',['../group__options.html#ggafebf7ed116adb38ae5218bc3ce06884ca7c8b7bf5281c581bad64f5daa6442777',1,'mimalloc-doc.h']]] diff --git a/docs/search/functions_0.js b/docs/search/functions_0.js index 7a48746a..2c169f9a 100644 --- a/docs/search/functions_0.js +++ b/docs/search/functions_0.js @@ -51,6 +51,8 @@ var searchData= ['mi_5fmemalign',['mi_memalign',['../group__posix.html#gaab7fa71ea93b96873f5d9883db57d40e',1,'mimalloc-doc.h']]], ['mi_5fnew',['mi_new',['../group__posix.html#gaad048a9fce3d02c5909cd05c6ec24545',1,'mimalloc-doc.h']]], ['mi_5fnew_5faligned',['mi_new_aligned',['../group__posix.html#gaef2c2bdb4f70857902d3c8903ac095f3',1,'mimalloc-doc.h']]], + ['mi_5fnew_5faligned_5fnothrow',['mi_new_aligned_nothrow',['../group__posix.html#gab5e29558926d934c3f1cae8c815f942c',1,'mimalloc-doc.h']]], + ['mi_5fnew_5fnothrow',['mi_new_nothrow',['../group__posix.html#gaeaded64eda71ed6b1d569d3e723abc4a',1,'mimalloc-doc.h']]], ['mi_5foption_5fenable',['mi_option_enable',['../group__options.html#ga6d45a20a3131f18bc351b69763b38ce4',1,'mimalloc-doc.h']]], ['mi_5foption_5fenable_5fdefault',['mi_option_enable_default',['../group__options.html#ga37988264b915a7db92530cc02d5494cb',1,'mimalloc-doc.h']]], ['mi_5foption_5fenabled',['mi_option_enabled',['../group__options.html#gacebe3f6d91b4a50b54eb84e2a1da1b30',1,'mimalloc-doc.h']]], diff --git a/docs/using.html b/docs/using.html index 9b7305b0..04e180ef 100644 --- a/docs/using.html +++ b/docs/using.html @@ -104,7 +104,16 @@ $(document).ready(function(){initNavTree('using.html','');});

The preferred usage is including <mimalloc.h>, linking with the shared- or static library, and using the mi_malloc API exclusively for allocation. For example,

gcc -o myprogram -lmimalloc myfile.c

mimalloc uses only safe OS calls (mmap and VirtualAlloc) and can co-exist with other allocators linked to the same program. If you use cmake, you can simply use:

find_package(mimalloc 1.0 REQUIRED)

in your CMakeLists.txt to find a locally installed mimalloc. Then use either:

target_link_libraries(myapp PUBLIC mimalloc)

to link with the shared (dynamic) library, or:

target_link_libraries(myapp PUBLIC mimalloc-static)

to link with the static library. See test\CMakeLists.txt for an example.

You can pass environment variables to print verbose messages (MIMALLOC_VERBOSE=1) and statistics (MIMALLOC_SHOW_STATS=1) (in the debug version):

> env MIMALLOC_SHOW_STATS=1 ./cfrac 175451865205073170563711388363
175451865205073170563711388363 = 374456281610909315237213 * 468551
heap stats: peak total freed unit
normal 2: 16.4 kb 17.5 mb 17.5 mb 16 b ok
normal 3: 16.3 kb 15.2 mb 15.2 mb 24 b ok
normal 4: 64 b 4.6 kb 4.6 kb 32 b ok
normal 5: 80 b 118.4 kb 118.4 kb 40 b ok
normal 6: 48 b 48 b 48 b 48 b ok
normal 17: 960 b 960 b 960 b 320 b ok
heap stats: peak total freed unit
normal: 33.9 kb 32.8 mb 32.8 mb 1 b ok
huge: 0 b 0 b 0 b 1 b ok
total: 33.9 kb 32.8 mb 32.8 mb 1 b ok
malloc requested: 32.8 mb
committed: 58.2 kb 58.2 kb 58.2 kb 1 b ok
reserved: 2.0 mb 2.0 mb 2.0 mb 1 b ok
reset: 0 b 0 b 0 b 1 b ok
segments: 1 1 1
-abandoned: 0
pages: 6 6 6
-abandoned: 0
mmaps: 3
mmap fast: 0
mmap slow: 1
threads: 0
elapsed: 2.022s
process: user: 1.781s, system: 0.016s, faults: 756, reclaims: 0, rss: 2.7 mb

The above model of using the mi_ prefixed API is not always possible though in existing programs that already use the standard malloc interface, and another option is to override the standard malloc interface completely and redirect all calls to the mimalloc library instead.

-

See Overriding Malloc for more info.

+

See Overriding Malloc for more info.

+

Environment Options

+

You can set further options either programmatically (using mi_option_set), or via environment variables.

+
    +
  • MIMALLOC_SHOW_STATS=1: show statistics when the program terminates.
    • +
  • MIMALLOC_VERBOSE=1: show verbose messages.
    • +
  • 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 and Linux).
    • +
  • 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.
    • +