mimalloc-doc.h

/* ----------------------------------------------------------------------------
Copyright (c) 2018-2025, 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_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_good_size(size_t 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(sizeof(tp)))
 
#define mi_zalloc_tp(tp)        ((tp*)mi_zalloc(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_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_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);
 
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_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_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_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);
 
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);
 
 
void mi_debug_show_arenas(void);
 
void* mi_arena_area(mi_arena_id_t arena_id, size_t* size);
 
 
 
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_SIZE_MAX   (128*sizeof(void*))
 
int  mi_version(void);
 
void mi_collect(bool force);
 
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_zalloc_small(size_t size);
 
 
 
// ------------------------------------------------------
// 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_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);
 
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);
 
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);
 
 
// ------------------------------------------------------
// 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_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);
 
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_zalloc(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_small(mi_theap_t* theap, 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_cfree(void* p);
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);
 
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_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);
 
template<class T> struct mi_stl_allocator { }