1 // Written in the D programming language.
2 /**
3 This module provides low-level bindings with the mimalloc C interface
4 Copyright: Copyright 2019 Ernesto Castellotti <erny.castell@gmail.com>
5 License:   $(HTTP https://www.mozilla.org/en-US/MPL/2.0/, Mozilla Public License - Version 2.0).
6 Authors:   $(HTTP github.com/ErnyTech, Ernesto Castellotti)
7 */
8 module neomimalloc.c.mimalloc;
9 
10 import core.stdc.config : c_long;
11 import core.stdc.stdio: FILE;
12 
13 extern(C) {
14     /**
15      * The mimalloc version
16      */
17     enum MI_MALLOC_VERSION = 100;
18 
19     /**
20      * Internal use
21      */
22     enum MI_SMALL_WSIZE_MAX = 128;
23 
24     /**
25      * Maximum size allowed for small allocations in mi_malloc_small and mi_zalloc_small (usually 128*sizeof(void*) (= 1KB on 64-bit systems))
26      */
27     enum MI_SMALL_SIZE_MAX = MI_SMALL_WSIZE_MAX * (void*).sizeof;
28 
29     /**
30      * Type of deferred free functions.
31      * 
32      * Params:
33      *      force = If true all outstanding items should be freed.
34      *      heartbeat = A monotonically increasing count.
35      *
36      * Most detailed when using a debug build.
37      */
38     alias mi_deferred_free_fun = void function(bool force, ulong heartbeat);
39 
40     /**
41      * Type of first-class heaps.
42      *
43      * A heap can only be used for (re)allocation in the thread that created this heap! Any allocated blocks can be freed by any other thread though.
44      */
45     struct mi_heap_t;
46 
47     /**
48      * An area of heap space contains blocks of a single size.
49      *
50      * The bytes in freed blocks are committed - used.
51      */
52     struct mi_heap_area_t {
53         void* blocks;       /** start of the area containing heap blocks */
54         size_t reserved;    /** bytes reserved for this area (virtual) */
55         size_t committed;   /** current available bytes for this area */
56         size_t used;        /** bytes in use by allocated blocks */
57         size_t block_size;  /** size in bytes of each block */
58     }
59 
60     /**
61      * Visitor function passed to mi_heap_visit_blocks()
62      *
63      * Returns:
64      *      true if ok, false to stop visiting (i.e. break)
65      * 
66      * This function is always first called for every area with block as a NULL pointer. If visit_all_blocks was true, the function is then called for every allocated block in that area.
67      */
68     alias mi_block_visit_fun = bool function(const(mi_heap_t)* heap, 
69                                             const(mi_heap_area_t)* area, 
70                                             void* block, size_t block_size, 
71                                             const(void)* arg);
72 
73     /**
74      * Runtime options.
75      */
76     enum mi_option_t {
77         mi_option_page_reset = 0,       /** Reset page memory when it becomes free. */
78         mi_option_cache_reset = 1,      /** Reset segment memory when a segment is cached. */
79         mi_option_pool_commit = 2,      /** Commit segments in large pools. */
80         mi_option_secure = 3,           
81         mi_option_show_stats = 4,       /** Print statistics to stderr when the program is done. */
82         mi_option_show_errors = 5,      /** Print error messages to stderr. */
83         mi_option_verbose = 6,          /** Print verbose messages to stderr. */
84         _mi_option_last = 7
85 }
86 
87     /**
88      * Allocate size bytes.
89      * 
90      * Params:
91      *      size = number of bytes to allocate.
92      *
93      * Returns:
94      *      pointer to the allocated memory or NULL if out of memory. Returns a unique pointer if called with size 0.
95      */
96     @nogc pure @system nothrow void* mi_malloc(size_t size);
97 
98     /**
99      * Allocate count elements of size bytes.
100      * 
101      * Params:
102      *      count = The number of elements.
103      *      size = The size of each element.
104      *
105      * Returns:
106      *      A pointer to a block of count * size bytes, or NULL if out of memory or if count * size overflows.
107      *
108      * If there is no overflow, it behaves exactly like mi_malloc(p,count*size).
109      */
110     @nogc pure @system nothrow void* mi_mallocn(size_t count, size_t size);
111 
112     /**
113      * Allocate zero-initialized count elements of size bytes.
114      * 
115      * Params:
116      *      count = number of elements.
117      *      size = size of each element.
118      *
119      * Returns:
120      *      pointer to the allocated memory of size*count bytes, or NULL if either out of memory or when count*size overflows.
121      *
122      * Returns a unique pointer if called with either size or count of 0.
123      */
124     @nogc pure @system nothrow void* mi_calloc(size_t count, size_t size);
125 
126     /**
127      * Re-allocate memory to newsize bytes.
128      * 
129      * Params:
130      *      p = pointer to previously allocated memory (or NULL).
131      *      newsize = the new required size in bytes.
132      *
133      * Returns:
134      *      pointer to the re-allocated memory of newsize bytes, or NULL if out of memory. If NULL is returned, the pointer p is not freed. Otherwise the original pointer is either freed or returned as the reallocated result (in case it fits in-place with the new size). If the pointer p is NULL, it behaves as mi_malloc(newsize). If newsize is larger than the original size allocated for p, the bytes after size are uninitialized.
135      */
136     @nogc pure @system nothrow void* mi_realloc(void* p, size_t newsize);
137 
138     /**
139      * Re-allocate memory to newsize bytes.
140      * 
141      * Params:
142      *      p = pointer to previously allocated memory (or NULL).
143      *      newsize = the new required size in bytes.
144      *
145      * Returns:
146      *      pointer to the re-allocated memory of newsize bytes, or NULL if out of memory.
147      *
148      * In contrast to mi_realloc(), if NULL is returned, the original pointer p is freed (if it was not NULL itself). Otherwise the original pointer is either freed or returned as the reallocated result (in case it fits in-place with the new size). If the pointer p is NULL, it behaves as mi_malloc(newsize). If newsize is larger than the original size allocated for p, the bytes after size are uninitialized.
149      */
150     @nogc pure @system nothrow void* mi_reallocf(void* p, size_t newsize);
151 
152     /**
153      * Re-allocate memory to count elements of size bytes.
154      * 
155      * Params:
156      *      p = Pointer to a previously allocated block (or NULL).
157      *      count = The number of elements.
158      *      size = The size of each element.
159      *
160      * Returns:
161      *      A pointer to a re-allocated block of count * size bytes, or NULL if out of memory or if count * size overflows.
162      *
163      * If there is no overflow, it behaves exactly like mi_realloc(p,count*size).
164      */
165     @nogc pure @system nothrow void* mi_reallocn(void* p, size_t count, size_t size);
166 
167     /**
168      * Allocate zero-initialized size bytes.
169      * 
170      * Params:
171      *      size = The size in bytes.
172      *
173      * Returns:
174      *      Pointer to newly allocated zero initialized memory, or NULL if out of memory.
175      */
176     @nogc pure @system nothrow void* mi_zalloc(size_t size);
177     
178     /**
179      * Reallocate memory to newsize bytes, with extra memory initialized to zero.
180      * 
181      * Params:
182      *      p = Pointer to a previously allocated block (or NULL).
183      *      newsize = The new required size in bytes.
184      *
185      * Returns:
186      *      A pointer to a re-allocated block of newsize bytes, or NULL if out of memory.
187      *
188      * If the newsize is larger than the original allocated size of p, the extra bytes are initialized to zero.
189      */
190     @nogc pure @system nothrow void* mi_rezalloc(void* p, size_t newsize);
191 
192     /**
193      * Re-allocate memory to newsize bytes.
194      * 
195      * Params:
196      *      p = pointer to previously allocated memory (or NULL).
197      *      newsize = the new required size in bytes.
198      *
199      * Returns:
200      *      pointer to the re-allocated memory of newsize bytes, or NULL if out of memory. If NULL is returned, the pointer p is not freed. Otherwise the original pointer is either freed or returned as the reallocated result (in case it fits in-place with the new size). If the pointer p is NULL, it behaves as mi_malloc(newsize). If newsize is larger than the original size allocated for p, the bytes after size are uninitialized.
201      */
202     @nogc pure @system nothrow void* mi_recalloc(void* p, size_t count, size_t size);
203 
204     /**
205      * Try to re-allocate memory to newsize bytes in place.
206      * 
207      * Params:
208      *      p = pointer to previously allocated memory (or NULL).
209      *      newsize = the new required size in bytes.
210      *
211      * Returns:
212      *      pointer to the re-allocated memory of newsize bytes (always equal to p), or NULL if either out of memory or if the memory could not be expanded in place. If NULL is returned, the pointer p is not freed. Otherwise the original pointer is returned as the reallocated result since it fits in-place with the new size. If newsize is larger than the original size allocated for p, the bytes after size are uninitialized.
213      */
214     @nogc pure @system nothrow void* mi_expand(void* p, size_t newsize);
215 
216     /**
217      * Free previously allocated memory.
218      *
219      * The pointer p must have been allocated before (or be NULL).
220      * 
221      * Params:
222      *      p = pointer to free, or NULL.
223      */
224     @nogc pure @system nothrow void mi_free(void* p);
225 
226     /**
227      * Allocate and duplicate a string.
228      * 
229      * Params:
230      *      s = string to duplicate (or NULL).
231      *
232      * Returns:
233      *      a pointer to newly allocated memory initialized to string s, or NULL if either out of memory or if s is NULL.
234      *
235      * Replacement for the standard strdup() such that mi_free() can be used on the returned result.
236      */
237     @nogc pure @system nothrow char* mi_strdup(const(char)* s);
238 
239     /**
240      * Allocate and duplicate a string up to n bytes.
241      * 
242      * Params:
243      *      s = string to duplicate (or NULL).
244      *      n = maximum number of bytes to copy (excluding the terminating zero).
245      *
246      * Returns:
247      *      a pointer to newly allocated memory initialized to string s up to the first n bytes (and always zero terminated), or NULL if either out of memory or if s is NULL.
248      *
249      * Replacement for the standard strndup() such that mi_free() can be used on the returned result.
250      */
251     @nogc pure @system nothrow char* mi_strndup(const(char)* s, size_t n);
252 
253     /**
254      * Resolve a file path name.
255      * 
256      * Params:
257      *      fname = File name.
258      *      resolved_name = Should be NULL (but can also point to a buffer of at least PATH_MAX bytes).
259      *
260      * Returns:
261      *      If successful a pointer to the resolved absolute file name, or NULL on failure (with errno set to the error code).
262      *
263      * If resolved_name was NULL, the returned result should be freed with mi_free().
264      *
265      * Replacement for the standard realpath() such that mi_free() can be used on the returned result (if resolved_name was NULL).
266      */
267     @nogc pure @system nothrow char* mi_realpath(const(char)* fname, char* resolved_name);
268 
269     /**
270      * Allocate a small object.
271      * 
272      * Params:
273      *      size = The size in bytes, can be at most MI_SMALL_SIZE_MAX.
274      *
275      * Returns:
276      *      a pointer to newly allocated memory of at least size bytes, or NULL if out of memory. This function is meant for use in run-time systems for best performance and does not check if size was indeed small – use with care!
277      */
278     @nogc pure @system nothrow void* mi_malloc_small(size_t size);
279     
280     /**
281      * Allocate a zero initialized small object.
282      * 
283      * Params:
284      *      size = The size in bytes, can be at most MI_SMALL_SIZE_MAX.
285      *
286      * Returns:
287      *      a pointer to newly allocated zero-initialized memory of at least size bytes, or NULL if out of memory. This function is meant for use in run-time systems for best performance and does not check if size was indeed small – use with care!
288      */
289     @nogc pure @system nothrow void* mi_zalloc_small (size_t size);
290     
291     /**
292      * Return the available bytes in a memory block.
293      * 
294      * Params:
295      *      p = Pointer to previously allocated memory (or NULL)
296      *
297      * Returns:
298      *      Returns the available bytes in the memory block, or 0 if p was NULL.
299      *
300      * The returned size can be used to call mi_expand successfully. The returned size is always at least equal to the allocated size of p, and, in the current design, should be less than 16.7% more.
301      */
302     @nogc pure @system nothrow size_t mi_usable_size(const(void)* p);
303     
304     /**
305      * Return the used allocation size.
306      * 
307      * Params:
308      *      size = The minimal required size in bytes.
309      *
310      * Returns:
311      *      the size n that will be allocated, where n >= size.
312      *
313      * Generally, mi_usable_size(mi_malloc(size)) == mi_good_size(size). This can be used to reduce internal wasted space when allocating buffers for example.
314      */
315     @nogc pure @system nothrow size_t mi_good_size(size_t size);
316     
317     /**
318      * Eagerly free memory.
319      * 
320      * Params:
321      *      force = If true, aggressively return memory to the OS (can be expensive!)
322      *
323      * Regular code should not have to call this function. It can be beneficial in very narrow circumstances; in particular, when a long running thread allocates a lot of blocks that are freed by other threads it may improve resource usage by calling this every once in a while.
324      */
325     @nogc pure @system nothrow void mi_collect(bool force);
326     
327     /**
328      * Print statistics.
329      * 
330      * Params:
331      *      out_ = Output file. Use NULL for stderr.
332      *
333      * Most detailed when using a debug build.
334      */
335     @nogc pure @system nothrow void mi_stats_print(FILE* out_);
336     
337     /**
338      * Reset statistics.
339      */
340     @nogc @system nothrow void mi_stats_reset();
341     
342     /**
343      * Initialize mimalloc on a process
344      */
345     @nogc @system nothrow void mi_process_init();
346     
347     /**
348      * Initialize mimalloc on a thread.
349      *
350      * Should not be used as on most systems (pthreads, windows) this is done automatically.
351      */
352     @nogc @system nothrow void mi_thread_init();
353     
354     /**
355      * Uninitialize mimalloc on a thread.
356      *
357      * Should not be used as on most systems (pthreads, windows) this is done automatically. Ensures that any memory that is not freed yet (but will be freed by other threads in the future) is properly handled.
358      */
359     @nogc @system nothrow void mi_thread_done();
360     
361     /**
362      * Print out heap statistics for this thread.
363      * 
364      * Params:
365      *      out_ = Output file. Use NULL for stderr.
366      *
367      * Most detailed when using a debug build.
368      */
369     @nogc pure @system nothrow void mi_thread_stats_print(FILE* out_);
370     
371     /**
372      * Register a deferred free function.
373      * 
374      * Params:
375      *      deferred_free = Address of a deferred free-ing function or NULL to unregister.
376      *
377      * Some runtime systems use deferred free-ing, for example when using reference counting to limit the worst case free time. Such systems can register (re-entrant) deferred free function to free more memory on demand. When the force parameter is true all possible memory should be freed. The per-thread heartbeat parameter is monotonically increasing and guaranteed to be deterministic if the program allocates deterministically. The deferred_free function is guaranteed to be called deterministically after some number of allocations (regardless of freeing or available free memory). At most one deferred_free function can be active.
378      */
379     @nogc @system nothrow void mi_register_deferred_free(const(mi_deferred_free_fun) deferred_free);
380 
381     /**
382      * Allocate size bytes aligned by alignment.
383      * 
384      * Params:
385      *      size = number of bytes to allocate.
386      *      alignment = the minimal alignment of the allocated memory.
387      *
388      * Returns:
389      *      pointer to the allocated memory or NULL if out of memory. The returned pointer is aligned by alignment, i.e. (uintptr_t)p % alignment == 0.
390      *
391      * Returns a unique pointer if called with size 0.
392      */
393     @nogc pure @system nothrow void* mi_malloc_aligned(size_t size, size_t alignment);
394     
395     /**
396      * Allocate size bytes aligned by alignment at a specified offset.
397      * 
398      * Params:
399      *      size = number of bytes to allocate.
400      *      alignment = the minimal alignment of the allocated memory at offset.
401      *      offset = the offset that should be aligned.
402      *
403      * Returns:
404      *      pointer to the allocated memory or NULL if out of memory. The returned pointer is aligned by alignment at offset, i.e. ((uintptr_t)p + offset) % alignment == 0.
405      *
406      * Returns a unique pointer if called with size 0.
407      */
408     @nogc pure @system nothrow void* mi_malloc_aligned_at(size_t size, size_t alignment, size_t offset);
409     
410     /**
411      * Allocate zero-initialized size bytes aligned by alignment.
412      */
413     @nogc pure @system nothrow void* mi_zalloc_aligned(size_t size, size_t alignment);
414     
415     /**
416      * Allocate zero-initialized size bytes aligned by alignment at a specified offset.
417      */
418     @nogc pure @system nothrow void* mi_zalloc_aligned_at(size_t size, size_t alignment, size_t offset);
419     
420     /**
421      * Allocate zero-initialized count elements of size bytes aligned by alignment.
422      */
423     @nogc pure @system nothrow void* mi_calloc_aligned(size_t count, size_t size, size_t alignment);
424     
425     /**
426      * Allocate zero-initialized count elements of size bytes aligned by alignment at a specified offset.
427      */
428     void* mi_calloc_aligned_at(size_t count, size_t size, size_t alignment, size_t offset);
429     
430     /**
431      * Re-allocate memory to newsize bytes aligned by alignment.
432      */
433     @nogc pure @system nothrow void* mi_realloc_aligned(void* p, size_t newsize, size_t alignment);
434     
435     /**
436      * Re-allocate memory to newsize bytes aligned by alignment at a specified offset.
437      */
438     @nogc pure @system nothrow void* mi_realloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);
439     
440     /**
441      * Reallocate memory to newsize bytes, with extra memory initialized to zero aligned by alignment.
442      */
443     @nogc pure @system nothrow void* mi_rezalloc_aligned(void* p, size_t newsize, size_t alignment);
444     
445    /**
446      * Reallocate memory to newsize bytes, with extra memory initialized to zero aligned by alignment at a specified offset.
447      */
448     @nogc pure @system nothrow void* mi_rezalloc_aligned_at(void* p, size_t newsize, size_t alignment, size_t offset);
449     
450     /**
451      * Re-allocate memory to newsize bytes aligned by alignment.
452      */
453     @nogc pure @system nothrow void* mi_recalloc_aligned(void* p, size_t count, size_t size, size_t alignment);
454     
455     /**
456      * Re-allocate memory to newsize bytes aligned by alignment at a specified offset.
457      */
458     @nogc pure @system nothrow void* mi_recalloc_aligned_at(void* p, size_t count, size_t size, size_t alignment, size_t offset);
459 
460     /**
461      * Create a new heap that can be used for allocation.
462      */
463     @nogc pure @system nothrow mi_heap_t* mi_heap_new();
464     
465     /**
466      * Delete a previously allocated heap.
467      *
468      * This will release resources and migrate any still allocated blocks in this heap (efficienty) to the default heap.
469      * 
470      * If heap is the default heap, the default heap is set to the backing heap.
471      */
472     @nogc pure @system nothrow void mi_heap_delete(mi_heap_t* heap);
473     
474     /**
475      * Destroy a heap, freeing all its still allocated blocks.
476      *
477      * Use with care as this will free all blocks still allocated in the heap. However, this can be a very efficient way to free all heap memory in one go.
478      * 
479      * If heap is the default heap, the default heap is set to the backing heap.
480      */
481     @nogc pure @system nothrow void mi_heap_destroy(mi_heap_t* heap);
482     
483     /**
484      * Set the default heap to use for mi_malloc() et al.
485      * 
486      * Params:
487      *      heap = The new default heap.
488      *
489      * Returns:
490      *      The previous default heap.
491      */
492     @nogc pure @system nothrow mi_heap_t* mi_heap_set_default(mi_heap_t* heap);
493     
494     /**
495      * Get the default heap that is used for mi_malloc() et al.
496      * 
497      * Returns:
498      *      The current default heap.
499      */
500     @nogc pure @system nothrow mi_heap_t* mi_heap_get_default();
501     
502     /**
503      * Get the backing heap.
504      *
505      * The backing heap is the initial default heap for a thread and always available for allocations. It cannot be destroyed or deleted except by exiting the thread.
506      */
507     @nogc pure @system nothrow mi_heap_t* mi_heap_get_backing();
508     
509     /**
510      * Eagerly free memory in specific heap.
511      */ 
512     @nogc pure @system nothrow void mi_heap_collect(mi_heap_t* heap, bool force);
513     
514     /**
515      * Allocate in a specific heap.
516      */
517     @nogc pure @system nothrow void* mi_heap_malloc(mi_heap_t* heap, size_t size);
518 
519     /**
520      * Allocate count elements in a specific heap.
521      */
522     @nogc pure @system nothrow void* mi_heap_mallocn(mi_heap_t* heap, size_t count, size_t size);
523 
524     /**
525      * Allocate zero-initialized in a specific heap.
526      */
527     @nogc pure @system nothrow void* mi_heap_zalloc(mi_heap_t* heap, size_t size);
528     
529     /**
530      * Allocate count zero-initialized elements in a specific heap.
531      */
532     @nogc pure @system nothrow void* mi_heap_calloc(mi_heap_t* heap, size_t count, size_t size);
533     
534     /**
535      * Allocate a small object in a specific heap.
536      */
537     @nogc pure @system nothrow void* mi_heap_malloc_small(mi_heap_t* heap, size_t size);
538 
539     /**
540      * Duplicate a string in a specific heap.
541      */
542     @nogc pure @system nothrow char* mi_heap_strdup(mi_heap_t* heap, const(char)* s);
543 
544     /**
545      * Duplicate a string of at most length n in a specific heap.
546      */
547     @nogc pure @system nothrow char* mi_heap_strndup(mi_heap_t* heap, const(char)* s, size_t n);
548     
549     /**
550      * Resolve a file path name using a specific heap to allocate the result.
551      */
552     @nogc pure @system nothrow char* mi_heap_realpath(mi_heap_t* heap, const(char)* fname, char* resolved_name);
553 
554     /**
555      * Does a heap contain a pointer to a previously allocated block?
556      * 
557      * Params:
558      *      heap = The heap.
559      *      p = Pointer to a previously allocated block (in any heap)– cannot be some random pointer!
560      *
561      * Returns:
562      *      true if the block pointed to by p is in the heap.
563      */
564     @nogc pure @system nothrow bool mi_heap_contains_block(mi_heap_t* heap, const(void)* p);
565     
566     /**
567      * Check safely if any pointer is part of a heap.
568      * 
569      * Params:
570      *      heap = The heap.
571      *      p = Any pointer – not required to be previously allocated by us.
572      *
573      * Returns:
574      *      true if p points to a block in heap.
575      *
576      * Note: expensive function, linear in the pages in the heap.
577      */
578     @nogc pure @system nothrow bool mi_heap_check_owned(mi_heap_t* heap, const(void)* p);
579     
580     /**
581      * Check safely if any pointer is part of the default heap of this thread.
582      * 
583      * Params:
584      *      p = Any pointer – not required to be previously allocated by us.
585      *
586      * Returns:
587      *      true if p points to a block in default heap of this thread.
588      *
589      * Note: expensive function, linear in the pages in the heap.
590      */
591     @nogc pure @system nothrow bool mi_check_owned(const(void)* p);
592 
593     /**
594      * Visit all areas and blocks in a heap.
595      * 
596      * Params:
597      *      heap = The heap to visit.
598      *      visit_all_blocks = If true visits all allocated blocks, otherwise visitor is only called for every heap area.
599      *      visitor = This function is called for every area in the heap (with block as NULL). If visit_all_blocks is true, visitor is also called for every allocated block in every area (with block!=NULL). return false from this function to stop visiting early.
600      *      arg = 	Extra argument passed to visitor.
601      *
602      * Returns:
603      *      true if all areas and blocks were visited.
604      */
605     @nogc pure @system nothrow bool mi_heap_visit_blocks(const(mi_heap_t)* heap, bool visit_all_blocks, mi_block_visit_fun visitor, const(void)* arg);
606 
607     /**
608      * Set runtime behavior.
609      */
610     @nogc pure @system nothrow bool mi_option_is_enabled(mi_option_t option);
611 
612     /**
613      * Set runtime behavior.
614      */
615     @nogc @system nothrow void mi_option_enable(mi_option_t option, bool enable);
616 
617     /**
618      * Set runtime behavior.
619      */
620     @nogc @system nothrow void mi_option_enable_default(mi_option_t option, bool enable);
621 
622     /**
623      * Set runtime behavior.
624      */
625     @nogc pure @system nothrow c_long mi_option_get(mi_option_t option);
626 
627     /**
628      * Set runtime behavior.
629      */
630     @nogc @system nothrow void mi_option_set(mi_option_t option, c_long value);
631 
632     /**
633      * Set runtime behavior.
634      */
635     @nogc @system nothrow void mi_option_set_default(mi_option_t option, c_long value);
636 }