mimalloc-doc.h

/* ----------------------------------------------------------------------------
Copyright (c) 2018, 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_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);


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



typedef enum mi_option_e {
  // stable options
  mi_option_show_errors,  
  mi_option_show_stats,   
  mi_option_verbose,      
  // the following options are experimental
  mi_option_eager_commit, 
  mi_option_eager_region_commit, 
  mi_option_large_os_pages,      
  mi_option_reserve_huge_os_pages, 
  mi_option_segment_cache,   
  mi_option_page_reset,      
  mi_option_segment_reset,   
  mi_option_reset_delay,     
  mi_option_use_numa_nodes,  
  mi_option_reset_decommits, 
  mi_option_eager_commit_delay,  
  mi_option_os_tag,          
  _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);
void  mi_option_set(mi_option_t option, long value);
void  mi_option_set_default(mi_option_t option, long value);




void*  mi_recalloc(void* p, size_t count, size_t size);
size_t mi_malloc_size(const void* p);
size_t mi_malloc_usable_size(const void *p);

void   mi_cfree(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_reallocarray(void* p, size_t count, size_t size);

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 { }