mimalloc-doc.h

/* ----------------------------------------------------------------------------
Copyright (c) 2018-2026, Microsoft Research, Daan Leijen
This is free software; you can redistribute it and/or modify it under the
terms of the MIT license. A copy of the license can be found in the file
"LICENSE" at the root of this distribution.
-----------------------------------------------------------------------------*/
 
#error "documentation file only!"
 

 

 

void  mi_free(void* p);

void  mi_cfree(void* p);

void* mi_malloc(size_t size);

void* mi_zalloc(size_t size);

void* mi_calloc(size_t count, size_t size);

void* mi_realloc(void* p, size_t newsize);

void* mi_expand(void* p, size_t newsize);

void* mi_mallocn(size_t count, size_t size);

void* mi_reallocn(void* p, size_t count, size_t size);

void* mi_reallocf(void* p, size_t newsize);
 

char* mi_strdup(const char* s);

char* mi_strndup(const char* s, size_t n);

char* mi_realpath(const char* fname, char* resolved_name);

size_t mi_usable_size(void* p);

size_t mi_thread_id_of(const void* p);

size_t mi_good_size(size_t size);

 
 
// ------------------------------------------------------
// Allocation with block sizes
// ------------------------------------------------------


void* mi_umalloc(size_t size, size_t* block_size);

void* mi_ucalloc(size_t count, size_t size, size_t* block_size);

void* mi_urealloc(void* p, size_t newsize, size_t* block_size_pre, size_t* block_size_post);

void mi_ufree(void* p, size_t* block_size);

void* mi_umalloc_aligned(size_t size, size_t alignment, size_t* block_size);

void* mi_uzalloc_aligned(size_t size, size_t alignment, size_t* block_size);

void* mi_umalloc_small(size_t size, size_t* block_size);

void* mi_uzalloc_small(size_t size, size_t* block_size);

 
// ------------------------------------------------------
// Aligned allocation
// ------------------------------------------------------


void* mi_malloc_aligned(size_t size, size_t alignment);
void* mi_zalloc_aligned(size_t size, size_t alignment);
void* mi_calloc_aligned(size_t count, size_t size, size_t alignment);
void* mi_realloc_aligned(void* p, size_t newsize, size_t alignment);

void* mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset);
void* mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset);
void* mi_calloc_aligned_at(size_t count, size_t size, size_t alignment, size_t offset);
void* mi_realloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);

 


#define mi_malloc_tp(tp)        ((tp*)mi_malloc_csize(sizeof(tp)))

#define mi_free_tp(tp,p)        (mi_free_csize(p,sizeof(tp)))

#define mi_zalloc_tp(tp)        ((tp*)mi_zalloc_csize(sizeof(tp)))

#define mi_calloc_tp(tp,count)      ((tp*)mi_calloc(count,sizeof(tp)))

#define mi_mallocn_tp(tp,count)     ((tp*)mi_mallocn(count,sizeof(tp)))

#define mi_reallocn_tp(p,tp,count)  ((tp*)mi_reallocn(p,count,sizeof(tp)))

#define mi_heap_malloc_tp(tp,hp)        ((tp*)mi_heap_malloc(hp,sizeof(tp)))

#define mi_heap_zalloc_tp(tp,hp)        ((tp*)mi_heap_zalloc(hp,sizeof(tp)))

#define mi_heap_calloc_tp(tp,hp,count)      ((tp*)mi_heap_calloc(hp,count,sizeof(tp)))

#define mi_heap_mallocn_tp(tp,hp,count)     ((tp*)mi_heap_mallocn(hp,count,sizeof(tp)))

#define mi_heap_reallocn_tp(tp,hp,p,count)  ((tp*)mi_heap_reallocn(p,count,sizeof(tp)))

#define mi_heap_recalloc_tp(tp,hp,p,count)  ((tp*)mi_heap_recalloc(p,count,sizeof(tp)))



void* mi_malloc_csize(size_t size);
 
void* mi_zalloc_csize(size_t size);
 
void* mi_theap_malloc_csize(mi_theap_t* theap, size_t size);
 
void* mi_theap_zalloc_csize(mi_theap_t* theap, size_t size);

void mi_free_csize(void* p, size_t size);

void mi_free_csize_nonnull(void* p, size_t size);

void mi_free_csize_aligned(void* p, size_t size, size_t aligned);

void mi_free_csize_aligned_nonnull(void* p, size_t size, size_t aligned);



void* mi_recalloc(void* p, size_t count, size_t size);
 
void* mi_rezalloc(void* p, size_t newsize);
void* mi_recalloc(void* p, size_t newcount, size_t size) ;
 
void* mi_rezalloc_aligned(void* p, size_t newsize, size_t alignment);
void* mi_rezalloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);
void* mi_recalloc_aligned(void* p, size_t newcount, size_t size, size_t alignment);
void* mi_recalloc_aligned_at(void* p, size_t newcount, size_t size, size_t alignment, size_t offset);
 
void* mi_heap_rezalloc(mi_heap_t* heap, void* p, size_t newsize);
void* mi_heap_recalloc(mi_heap_t* heap, void* p, size_t newcount, size_t size);
 
void* mi_heap_rezalloc_aligned(mi_heap_t* heap, void* p, size_t newsize, size_t alignment);
void* mi_heap_rezalloc_aligned_at(mi_heap_t* heap, void* p, size_t newsize, size_t alignment, size_t offset);
void* mi_heap_recalloc_aligned(mi_heap_t* heap, void* p, size_t newcount, size_t size, size_t alignment);
void* mi_heap_recalloc_aligned_at(mi_heap_t* heap, void* p, size_t newcount, size_t size, size_t alignment, size_t offset);

 
 


struct mi_heap_s;

typedef struct mi_heap_s mi_heap_t;

mi_heap_t* mi_heap_new();

void mi_heap_delete(mi_heap_t* heap);

void mi_thread_heap_release(mi_heap_t* heap);

void mi_heap_destroy(mi_heap_t* heap);

mi_heap_t* mi_heap_set_default(mi_heap_t* heap);

mi_heap_t* mi_heap_get_default();

mi_heap_t* mi_heap_get_backing();

void mi_heap_set_numa_affinity(mi_heap_t* heap, int numa_node);

void mi_heap_set_debug_fill_preserve(mi_heap_t* heap, size_t preserve);

mi_heap_t* mi_heap_main(void);

mi_heap_t* mi_heap_of(const void* p);

bool mi_heap_contains(const mi_heap_t* heap, const void* p);

bool mi_any_heap_contains(const void* p);
 

bool mi_is_in_heap_region(const void* p);

bool mi_check_owned(const void* p);

bool mi_heap_contains_block(mi_heap_t* heap, const void* p);

bool mi_heap_check_owned(mi_heap_t* heap, const void* p);

void mi_heap_collect(mi_heap_t* heap, bool force);

void* mi_heap_malloc(mi_heap_t* heap, size_t size);

void* mi_heap_malloc_small(mi_heap_t* heap, size_t size);

void* mi_heap_zalloc(mi_heap_t* heap, size_t size);

void* mi_heap_zalloc_small(mi_heap_t* heap, size_t size);

void* mi_heap_calloc(mi_heap_t* heap, size_t count, size_t size);

void* mi_heap_mallocn(mi_heap_t* heap, size_t count, size_t size);

char* mi_heap_strdup(mi_heap_t* heap, const char* s);

char* mi_heap_strndup(mi_heap_t* heap, const char* s, size_t n);

char* mi_heap_realpath(mi_heap_t* heap, const char* fname, char* resolved_name);
 
void* mi_heap_realloc(mi_heap_t* heap, void* p, size_t newsize);
void* mi_heap_reallocn(mi_heap_t* heap, void* p, size_t count, size_t size);
void* mi_heap_reallocf(mi_heap_t* heap, void* p, size_t newsize);
 
void* mi_heap_malloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
void* mi_heap_malloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
void* mi_heap_zalloc_aligned(mi_heap_t* heap, size_t size, size_t alignment);
void* mi_heap_zalloc_aligned_at(mi_heap_t* heap, size_t size, size_t alignment, size_t offset);
void* mi_heap_calloc_aligned(mi_heap_t* heap, size_t count, size_t size, size_t alignment);
void* mi_heap_calloc_aligned_at(mi_heap_t* heap, size_t count, size_t size, size_t alignment, size_t offset);
void* mi_heap_realloc_aligned(mi_heap_t* heap, void* p, size_t newsize, size_t alignment);
void* mi_heap_realloc_aligned_at(mi_heap_t* heap, void* p, size_t newsize, size_t alignment, size_t offset);

 
 

 

typedef struct mi_heap_area_s {
  void*  blocks;      
  size_t reserved;    
  size_t committed;   
  size_t used;        
  size_t block_size;  
  size_t full_block_size; 
  int    heap_tag;    
} mi_heap_area_t;

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);

bool mi_heap_visit_blocks(const mi_heap_t* heap, bool visit_blocks, mi_block_visit_fun* visitor, void* arg);

bool mi_heap_visit_abandoned_blocks(mi_heap_t* heap, bool visit_blocks, mi_block_visit_fun* visitor, void* arg);

bool mi_unsafe_heap_page_is_under_utilized(mi_heap_t* heap, void* p, size_t perc_threshold);

bool mi_abandoned_visit_blocks(mi_subproc_id_t subproc_id, int heap_tag, bool visit_blocks, mi_block_visit_fun* visitor, void* arg);

 
// ------------------------------------------------------
// Arenas
// ------------------------------------------------------


typedef int mi_arena_id_t;

int  mi_reserve_os_memory(size_t size, bool commit, bool allow_large);

int mi_reserve_os_memory_ex(size_t size, bool commit, bool allow_large, bool exclusive, mi_arena_id_t* arena_id);

int mi_reserve_huge_os_pages_interleave(size_t pages, size_t numa_nodes, size_t timeout_msecs);

int mi_reserve_huge_os_pages_at(size_t pages, int numa_node, size_t timeout_msecs);

int mi_reserve_huge_os_pages(size_t pages, double max_secs, size_t* pages_reserved);

int   mi_reserve_huge_os_pages_at_ex(size_t pages, int numa_node, size_t timeout_msecs, bool exclusive, mi_arena_id_t* arena_id);

size_t mi_arena_min_alignment(void);

size_t mi_arena_min_size(void);

size_t mi_arena_max_object_size(void);

bool mi_manage_os_memory(void* start, size_t size, bool is_committed, bool is_large, bool is_zero, int numa_node);

bool  mi_manage_os_memory_ex(void* start, size_t size, bool is_committed, bool is_large, bool is_zero, int numa_node, bool exclusive, mi_arena_id_t* arena_id);

typedef bool (mi_commit_fun_t)(bool commit, void* start, size_t size, bool* is_zero, void* user_arg);

bool mi_manage_memory(void* start, size_t size, bool is_committed, bool is_pinned, bool is_zero, int numa_node, bool exclusive,
                      mi_commit_fun_t* commit_fun, void* commit_fun_arg, mi_arena_id_t* arena_id);
 

void mi_debug_show_arenas(void);

void mi_arenas_print(void);

void mi_arenas_purge(void);

void* mi_arena_area(mi_arena_id_t arena_id, size_t* size);

bool mi_arena_contains(mi_arena_id_t arena_id, const void* p);

mi_heap_t* mi_heap_new_in_arena(mi_arena_id_t arena_id);

mi_heap_t* mi_heap_new_ex(int heap_tag, bool allow_destroy, mi_arena_id_t arena_id);

 


typedef void* mi_subproc_id_t;

mi_subproc_id_t mi_subproc_main(void);

mi_subproc_id_t mi_subproc_current(void);

mi_subproc_id_t mi_subproc_new(void);

void mi_subproc_destroy(mi_subproc_id_t subproc);

void mi_subproc_delete(mi_subproc_id_t subproc);

void mi_subproc_add_current_thread(mi_subproc_id_t subproc);

typedef bool (mi_heap_visit_fun)(mi_heap_t* heap, void* arg);

bool mi_subproc_visit_heaps(mi_subproc_id_t subproc, mi_heap_visit_fun* visitor, void* arg);

 
 
// ------------------------------------------------------
// Extended functionality
// ------------------------------------------------------


#define MI_SMALL_WSIZE_MAX  128

#define MI_SMALL_SIZE_MAX   (MI_SMALL_WSIZE_MAX*sizeof(size_t))

int  mi_version(void);

void mi_collect(bool force);

void mi_collect_reduce(size_t target_thread_owned);

void mi_process_init(void);

void mi_process_done(void);

void mi_thread_set_in_threadpool(void);

bool mi_is_redirected();

void mi_thread_init(void);

void mi_thread_done(void);

typedef void (mi_deferred_free_fun)(bool force, unsigned long long heartbeat, void* arg);

void   mi_register_deferred_free(mi_deferred_free_fun* deferred_free, void* arg);

typedef void (mi_output_fun)(const char* msg, void* arg);

void mi_register_output(mi_output_fun* out, void* arg);

typedef void (mi_error_fun)(int err, void* arg);

void mi_register_error(mi_error_fun* errfun, void* arg);

void* mi_malloc_small(size_t size);

void* mi_wmalloc_small(size_t wsize);

void* mi_wzalloc_small(size_t wsize);

size_t mi_wsize_from_size(size_t size);

void* mi_zalloc_small(size_t size);

void mi_free_small(void* p);

void mi_free_small_nonnull(void* p);

void mi_free_small_local(void* p);

void mi_free_small_local_nonnull(void* p);

 
 
 
 
 
// ------------------------------------------------------
// Statistics
// ------------------------------------------------------


#define MI_STAT_VERSION   4

#define mi_stats_t_decl(name)

struct mi_stats_s {
  size_t size;
  size_t version;
};

typedef struct mi_stats_s mi_stats_t;

void mi_stats_header_init(mi_stats_t* stats);

void mi_stats_init(mi_stats_t* stats);
 

void mi_process_info_print(void);

void mi_process_info_print_out(mi_output_fun* out, void* arg);

void mi_process_info(size_t* elapsed_msecs, size_t* user_msecs, size_t* system_msecs, size_t* current_rss, size_t* peak_rss, size_t* current_commit, size_t* peak_commit, size_t* page_faults);
 

void mi_stats_print(void* out);

void mi_stats_print_out(mi_output_fun* out, void* arg);

void mi_thread_stats_print_out(mi_output_fun* out, void* arg);

bool mi_stats_get(mi_stats_t* stats);

char*  mi_stats_get_json(size_t buf_size, char* buf);

size_t  mi_stats_get_bin_size(size_t bin);

bool mi_heap_stats_get(mi_heap_t* heap, mi_stats_t* stats);

char* mi_heap_stats_get_json(mi_heap_t* heap, size_t buf_size, char* buf);      // use mi_free to free the result if the input buf == NULL

void mi_heap_stats_print_out(mi_heap_t* heap, mi_output_fun* out, void* arg);

void mi_heap_stats_merge_to_subproc(mi_heap_t* heap);

bool mi_subproc_stats_get(mi_subproc_id_t subproc_id, mi_stats_t* stats);

bool mi_subproc_stats_get_exclusive(mi_subproc_id_t subproc_id, mi_stats_t* stats);

bool mi_theap_stats_get(mi_theap_t* theap, mi_stats_t* stats);

void mi_theap_stats_merge_to_heap(mi_theap_t* theap);

char* mi_subproc_stats_get_json(mi_subproc_id_t subproc_id, size_t buf_size, char* buf);      // use mi_free to free the result if the input buf == NULL

void  mi_subproc_stats_print_out(mi_subproc_id_t subproc_id, mi_output_fun* out, void* arg);
 

void mi_subproc_heap_stats_print_out(mi_subproc_id_t subproc_id, mi_output_fun* out, void* arg);

char*  mi_stats_as_json( mi_stats_t* stats, size_t buf_size, char* buf);

void mi_stats_reset(void);

void mi_stats_merge(void);

 
// ------------------------------------------------------
// Heap Profiling
// ------------------------------------------------------


typedef struct mi_profiler_s mi_profiler_t;

mi_profiler_t* mi_pprof_profiler_new(size_t initial_threshold, const char* base_file_name, size_t alloc_interval_size, size_t inuse_interval_size, size_t time_interval_secs);

void mi_pprof_profiler_delete(mi_profiler_t* profiler);

bool mi_profile(mi_profiler_t* profiler);

bool mi_subproc_profile(mi_subproc_id_t subproc_id, mi_profiler_t* profiler);

bool mi_heap_profile(mi_heap_t* heap, mi_profiler_t* profiler);

void mi_heap_profile_disable(mi_heap_t* heap);

bool mi_profiler_start(mi_profiler_t* profiler);

bool mi_profiler_stop(mi_profiler_t* profiler);

void mi_profiler_snapshot(mi_profiler_t* profiler);

 
// ------------------------------------------------------
// Runtime Options
// ------------------------------------------------------


void mi_options_print(void);

void mi_options_print_out(mi_output_fun* out, void* arg);
 

typedef enum mi_option_e {
  // stable options
  mi_option_show_errors,  
  mi_option_show_stats,   
  mi_option_verbose,      
  mi_option_max_errors,                 
  mi_option_max_warnings,               
 
  // advanced options
  mi_option_reserve_huge_os_pages,    
  mi_option_reserve_huge_os_pages_at, 
  mi_option_reserve_os_memory,        
  mi_option_allow_large_os_pages,     
  mi_option_purge_decommits,          
  mi_option_arena_reserve,            
  mi_option_os_tag,                   
  mi_option_retry_on_oom,             
  mi_option_generic_collect,          
  mi_option_allow_thp,                
 
  // guard pages
  mi_option_guarded_min,              
  mi_option_guarded_max,              
  mi_option_unsafe_guarded_precise,   
  mi_option_guarded_sample_rate,      
  mi_option_guarded_sample_seed,      
 
  // experimental options
  mi_option_eager_commit,             
  mi_option_eager_commit_delay,       
  mi_option_arena_eager_commit,       
  mi_option_abandoned_page_purge,     
  mi_option_purge_delay,              
  mi_option_use_numa_nodes,           
  mi_option_disallow_os_alloc,        
  mi_option_max_segment_reclaim,        
  mi_option_destroy_on_exit,            
  mi_option_arena_purge_mult,           
  mi_option_abandoned_reclaim_on_free,  
  mi_option_purge_extend_delay,         
  mi_option_disallow_arena_alloc,       
  mi_option_visit_abandoned,            
  mi_option_target_segments_per_thread, 
 
  // v3 options
  mi_option_page_reclaim_on_free,       
  mi_option_page_full_retain,           
  mi_option_page_max_candidates,        
  mi_option_max_vabits,                 
  mi_option_pagemap_commit,             
  mi_option_page_commit_on_demand,      
  mi_option_page_max_reclaim,           
  mi_option_page_cross_thread_max_reclaim, 
  mi_option_minimal_purge_size,         
  mi_option_arena_max_object_size,      
 
  _mi_option_last
} mi_option_t;
 
 
bool  mi_option_is_enabled(mi_option_t option);
void  mi_option_enable(mi_option_t option);
void  mi_option_disable(mi_option_t option);
void  mi_option_set_enabled(mi_option_t option, bool enable);
void  mi_option_set_enabled_default(mi_option_t option, bool enable);
 
long   mi_option_get(mi_option_t option);
long   mi_option_get_clamp(mi_option_t option, long min, long max);
size_t mi_option_get_size(mi_option_t option);
 
void  mi_option_set(mi_option_t option, long value);
void  mi_option_set_default(mi_option_t option, long value);



struct mi_theap_s;

typedef struct mi_theap_s mi_theap_t;

mi_theap_t* mi_heap_theap(mi_heap_t* heap);

void mi_theap_collect(mi_theap_t* theap, bool force);

void mi_theap_delete(mi_theap_t* theap);

void mi_theap_quiescent_abandon(mi_theap_t* theap);

mi_theap_t* mi_theap_set_default(mi_theap_t* theap);

mi_theap_t* mi_theap_get_default();

void* mi_theap_malloc(mi_theap_t* theap, size_t size);

void* mi_theap_malloc_small(mi_theap_t* theap, size_t size);

void* mi_theap_wmalloc_small(mi_theap_t* theap, size_t wsize);

void* mi_theap_wzalloc_small(mi_theap_t* theap, size_t wsize);

void* mi_theap_zalloc(mi_theap_t* theap, size_t size);

void* mi_theap_zalloc_small(mi_theap_t* theap, size_t size);
 
void* mi_theap_calloc(mi_theap_t* theap, size_t count, size_t size);
void* mi_theap_malloc_aligned(mi_theap_t* theap, size_t size, size_t alignment);
void* mi_theap_realloc(mi_theap_t* theap, void* p, size_t newsize);

void* mi_theap_zalloc_aligned(mi_theap_t* theap, size_t size, size_t alignment);

void* mi_theap_rezalloc(mi_theap_t* theap, void* p, size_t newsize);

void* mi_theap_realloc_aligned(mi_theap_t* theap, void* p, size_t newsize, size_t alignment);

void* mi_theap_rezalloc_aligned(mi_theap_t* theap, void* p, size_t newsize, size_t alignment);

void mi_theap_guarded_set_sample_rate(mi_theap_t* theap, size_t sample_rate, size_t seed);

void mi_theap_guarded_set_size_bound(mi_theap_t* theap, size_t min, size_t max);

bool mi_theap_visit_blocks(const mi_theap_t* theap, bool visit_blocks, mi_block_visit_fun* visitor, void* arg);

 

 
void* mi__expand(void* p, size_t newsize);
 
size_t mi_malloc_size(const void* p);
size_t mi_malloc_good_size(size_t size);
size_t mi_malloc_usable_size(const void *p);
 
int mi_posix_memalign(void** p, size_t alignment, size_t size);
int mi__posix_memalign(void** p, size_t alignment, size_t size);
void* mi_memalign(size_t alignment, size_t size);
void* mi_valloc(size_t size);
void* mi_pvalloc(size_t size);

void* mi_aligned_alloc(size_t alignment, size_t size);

void mi_free_sized(void* p, size_t size);

void mi_free_aligned_sized(void* p, size_t alignment, size_t size);
 
unsigned short* mi_wcsdup(const unsigned short* s);
unsigned char*  mi_mbsdup(const unsigned char* s);
int mi_dupenv_s(char** buf, size_t* size, const char* name);
int mi_wdupenv_s(unsigned short** buf, size_t* size, const unsigned short* name);

void* mi_reallocarray(void* p, size_t count, size_t size);

int   mi_reallocarr(void* p, size_t count, size_t size);
 
void* mi_aligned_recalloc(void* p, size_t newcount, size_t size, size_t alignment);
void* mi_aligned_offset_recalloc(void* p, size_t newcount, size_t size, size_t alignment, size_t offset);

void mi_free_size(void* p, size_t size);

void mi_free_size_nonnull(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);



void* mi_new(std::size_t n) noexcept(false);

void* mi_new_n(size_t count, size_t size) noexcept(false);

void* mi_new_aligned(std::size_t n, std::align_val_t alignment) noexcept(false);

void* mi_new_nothrow(size_t n);

void* mi_new_aligned_nothrow(size_t n, size_t alignment);

void* mi_new_realloc(void* p, size_t newsize);

void* mi_new_reallocn(void* p, size_t newcount, size_t size);

void* mi_heap_alloc_new(mi_heap_t* heap, size_t size);

void* mi_heap_alloc_new_n(mi_heap_t* heap, size_t count, size_t size);

void* mi_theap_alloc_new(mi_theap_t* theap, size_t size);

void* mi_theap_alloc_new_n(mi_theap_t* theap, size_t count, size_t size);

void* mi_theap_alloc_new_nothrow(mi_theap_t* theap, size_t size);

template<class T> struct mi_stl_allocator { }