|
| 1 | +/* ---------------------------------------------------------------------------- |
| 2 | +Copyright (c) 2018-2024, Microsoft Research, Daan Leijen |
| 3 | +This is free software; you can redistribute it and/or modify it under the |
| 4 | +terms of the MIT license. A copy of the license can be found in the file |
| 5 | +"LICENSE" at the root of this distribution. |
| 6 | +-----------------------------------------------------------------------------*/ |
| 7 | +#pragma once |
| 8 | +#ifndef MIMALLOC_PROFILE_H |
| 9 | +#define MIMALLOC_PROFILE_H |
| 10 | + |
| 11 | +#include <stddef.h> |
| 12 | +#include <stdint.h> |
| 13 | +#include <stdbool.h> |
| 14 | +#include "mimalloc/atomic.h" |
| 15 | + |
| 16 | +// Forward declarations — full types come from types.h / internal.h. |
| 17 | +typedef struct mi_page_s mi_page_t; |
| 18 | +typedef struct mi_block_s mi_block_t; |
| 19 | +typedef struct mi_heap_s mi_heap_t; |
| 20 | + |
| 21 | +// ------------------------------------------------------------------ |
| 22 | +// Allocation record: one node per sampled live allocation, stored in |
| 23 | +// a singly-linked list at page->metadata. Opaque to callers; the |
| 24 | +// callbacks receive user_data directly. |
| 25 | +// |
| 26 | +// `ptr` — the sampled user pointer; used internally to match frees. |
| 27 | +// `user_data` — flexible array member for caller-owned metadata. |
| 28 | +// The number of bytes available is |
| 29 | +// _mi_profiler.record_extra_bytes, set at |
| 30 | +// mi_profiler_enable() time. Typical uses: a captured |
| 31 | +// stack trace, allocation size and weight for on_free, |
| 32 | +// a pointer to an external profiler node, or a timestamp. |
| 33 | +// The profiler does not initialize this region and never |
| 34 | +// reads it. |
| 35 | +// Alignment: user_data begins at offset sizeof(mi_alloc_record_t) |
| 36 | +// from the allocation base (2 * sizeof(void*): 16 bytes on 64-bit, |
| 37 | +// 8 bytes on 32-bit), so it is suitably aligned for any scalar or |
| 38 | +// pointer type. SIMD types requiring > 16-byte alignment are not |
| 39 | +// guaranteed to be aligned. |
| 40 | +// ------------------------------------------------------------------ |
| 41 | +typedef struct mi_alloc_record_s { |
| 42 | + void* ptr; |
| 43 | + struct mi_alloc_record_s* next; |
| 44 | + char user_data[]; // length = _mi_profiler.record_extra_bytes |
| 45 | +} mi_alloc_record_t; |
| 46 | + |
| 47 | +// ------------------------------------------------------------------ |
| 48 | +// User-supplied callbacks. |
| 49 | +// |
| 50 | +// on_alloc: called when a sample is taken. |
| 51 | +// `user_data` — caller-owned region (record_extra_bytes bytes); |
| 52 | +// may write anything here for use in on_free. |
| 53 | +// NULL if record_extra_bytes is 0. |
| 54 | +// `ptr` — the sampled user pointer. |
| 55 | +// `requested_size` — size passed by the caller to malloc/calloc/etc. |
| 56 | +// `usable_size` — actual usable bytes after size-class rounding; |
| 57 | +// reflects true memory consumption. |
| 58 | +// `threshold` — the threshold (bytes) that triggered this sample. |
| 59 | +// `bytes_since_last_sample` — bytes accumulated since the last sample; the |
| 60 | +// statistical weight of this sample. |
| 61 | +// `heap_tag` — tag of the heap that made the allocation, set via |
| 62 | +// mi_heap_new_ex(). Zero for the default heap. |
| 63 | +// Returns the number of bytes to accumulate before the next sample. |
| 64 | +// Returning 0 causes the next allocation to be sampled immediately. |
| 65 | +// |
| 66 | +// on_free: called when a sampled allocation is freed. |
| 67 | +// `user_data` — the same region written during on_alloc. Valid only |
| 68 | +// for the duration of the callback; do not retain the pointer. |
| 69 | +// `ptr` — the freed user pointer. |
| 70 | +// May be NULL if free-time notification is not needed. |
| 71 | +// ------------------------------------------------------------------ |
| 72 | +typedef size_t (*mi_profiler_alloc_cb)(void* user_data, void* ptr, size_t requested_size, size_t usable_size, size_t threshold, size_t bytes_since_last_sample, uint8_t heap_tag); |
| 73 | +typedef void (*mi_profiler_free_cb)(void* user_data, void* ptr); |
| 74 | + |
| 75 | +// ------------------------------------------------------------------ |
| 76 | +// Global profiler configuration. |
| 77 | +// |
| 78 | +// Profiling is one-way: once enabled it cannot be disabled. |
| 79 | +// |
| 80 | +// `enabled` is _Atomic(bool) so that mi_profiler_enable() can be called |
| 81 | +// from any thread. The store uses release order; reads in the inline |
| 82 | +// fast-path hooks (in internal.h) use relaxed order (sufficient to decide |
| 83 | +// whether to do any work); the slow path uses acquire order to ensure |
| 84 | +// on_alloc, on_free, and record_extra_bytes are visible before they are read. |
| 85 | +// ------------------------------------------------------------------ |
| 86 | +typedef struct mi_profiler_s { |
| 87 | + _Atomic(bool) enabled; |
| 88 | + mi_profiler_alloc_cb on_alloc; // non-NULL when enabled=true |
| 89 | + mi_profiler_free_cb on_free; // may be NULL |
| 90 | + size_t record_extra_bytes; // bytes allocated after each mi_alloc_record_t for user_data |
| 91 | +} mi_profiler_t; |
| 92 | + |
| 93 | +extern mi_profiler_t _mi_profiler; |
| 94 | + |
| 95 | +// ------------------------------------------------------------------ |
| 96 | +// Public API — must be called at most once. May be called from any |
| 97 | +// thread, before or after other threads have started. Each thread |
| 98 | +// samples its first allocation immediately; the on_alloc callback |
| 99 | +// controls all subsequent thresholds. |
| 100 | +// |
| 101 | +// Returns true on success, false if: |
| 102 | +// - profiling was already enabled (called more than once), or |
| 103 | +// - on_alloc is NULL, or |
| 104 | +// - on_free is NULL but record_extra_bytes > 0, or |
| 105 | +// - record_extra_bytes would overflow the record allocation size. |
| 106 | +// ------------------------------------------------------------------ |
| 107 | +bool mi_profiler_enable(size_t record_extra_bytes, mi_profiler_alloc_cb on_alloc, mi_profiler_free_cb on_free); |
| 108 | + |
| 109 | +// ------------------------------------------------------------------ |
| 110 | +// Slow-path implementations (defined in profile.c). |
| 111 | +// The inline fast-path wrappers are in internal.h so they have |
| 112 | +// access to the full type definitions they need. |
| 113 | +// ------------------------------------------------------------------ |
| 114 | +void _mi_profiler_on_alloc_slow(mi_heap_t* heap, mi_page_t* page, void* ptr, size_t size); |
| 115 | +void _mi_profiler_on_free_local_slow(mi_page_t* page, void* ptr); |
| 116 | +void _mi_profiler_on_free_collected_slow(mi_page_t* page, mi_block_t* head); |
| 117 | + |
| 118 | +#endif // MIMALLOC_PROFILE_H |
0 commit comments