mimalloc-doc.h

/* ----------------------------------------------------------------------------
Copyright (c) 2018-2021, 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_recalloc(void* p, size_t count, size_t size);
 
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);
 
 
// ------------------------------------------------------
// Extended functionality
// ------------------------------------------------------
 
 
#define MI_SMALL_SIZE_MAX   (128*sizeof(void*))
 
void* mi_malloc_small(size_t size);
 
void* mi_zalloc_small(size_t size);
 
size_t mi_usable_size(void* p);
 
size_t mi_good_size(size_t size);
 
void   mi_collect(bool force);
 
void mi_stats_print(void* out);
 
void mi_stats_print_out(mi_output_fun* out, void* arg);
 
void mi_stats_reset(void);
 
void mi_stats_merge(void);
 
void mi_thread_init(void);
 
void mi_thread_done(void);
 
void mi_thread_stats_print_out(mi_output_fun* out, void* arg);
 
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);
 
bool mi_is_in_heap_region(const void* p);
 
int  mi_reserve_os_memory(size_t size, bool commit, bool allow_large);
 
bool mi_manage_os_memory(void* start, size_t size, bool is_committed, bool is_large, bool is_zero, int numa_node);
 
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);
 
 
bool mi_is_redirected();
 
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_debug_show_arenas(bool show_inuse, bool show_abandoned, bool show_purge);
 
typedef int mi_arena_id_t;
 
void* mi_arena_area(mi_arena_id_t arena_id, size_t* size);
 
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);
 
int   mi_reserve_os_memory_ex(size_t size, bool commit, bool allow_large, bool exclusive, mi_arena_id_t* arena_id);
 
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);
 
mi_heap_t* mi_heap_new_in_arena(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_new(void);
 
void mi_subproc_delete(mi_subproc_id_t subproc);
 
void mi_subproc_add_current_thread(mi_subproc_id_t subproc);
 
 
 
// ------------------------------------------------------
// 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);
 
 
 
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_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);
 
 
 
 
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);
 
 
 
#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(hp,tp)        ((tp*)mi_heap_malloc(hp,sizeof(tp)))
 
#define mi_heap_zalloc_tp(hp,tp)        ((tp*)mi_heap_zalloc(hp,sizeof(tp)))
 
#define mi_heap_calloc_tp(hp,tp,count)      ((tp*)mi_heap_calloc(hp,count,sizeof(tp)))
 
#define mi_heap_mallocn_tp(hp,tp,count)     ((tp*)mi_heap_mallocn(hp,count,sizeof(tp)))
 
#define mi_heap_reallocn_tp(hp,p,tp,count)  ((tp*)mi_heap_reallocn(p,count,sizeof(tp)))
 
#define mi_heap_recalloc_tp(hp,p,tp,count)  ((tp*)mi_heap_recalloc(p,count,sizeof(tp)))
 
 
 
bool mi_heap_contains_block(mi_heap_t* heap, const void* p);
 
bool mi_heap_check_owned(mi_heap_t* heap, const void* p);
 
bool mi_check_owned(const void* p);
 
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; 
} 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_all_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);
 
 
 
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,             
 
  // 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_limit_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_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);
 
 
 
 
void   mi_cfree(void* p);
void* mi__expand(void* p, size_t newsize);
 
void*  mi_recalloc(void* p, size_t count, size_t size);
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 { }