feat: add profiling options

.github/workflows/main.yml

@@ -2,7 +2,7 @@ name: CI
 
 on:
   pull_request:
-    branches:    
+    branches:
       - 'master'
       - 'main'
   push:
@@ -21,6 +21,11 @@ jobs:
             nobgt: 0
             no_tests: 1
             tag: arm64
+          - name: aarch64-apple-darwin
+            target: aarch64-apple-darwin
+            nobgt: 0
+            no_tests: 1
+            tag: macos-14
           - name: x86_64-unknown-linux-gnu (nightly)
             target: x86_64-unknown-linux-gnu
             nobgt: 0

jemalloc-ctl/Cargo.toml

@@ -35,6 +35,7 @@ tikv-jemallocator = { path = "../jemallocator", version = "0.5.0" }
 
 [features]
 default = []
+profiling = ["tikv-jemalloc-sys/profiling"]
 use_std = [ "libc/use_std" ]
 disable_initial_exec_tls = ["tikv-jemalloc-sys/disable_initial_exec_tls"]
 

jemalloc-ctl/src/lib.rs

@@ -88,6 +88,8 @@ pub mod config;
 mod error;
 mod keys;
 pub mod opt;
+#[cfg(feature = "profiling")]
+pub mod profiling;
 pub mod raw;
 pub mod stats;
 #[cfg(feature = "use_std")]

jemalloc-ctl/src/profiling.rs

@@ -0,0 +1,155 @@
+//! `jemalloc`'s run-time configuration for profiling-specific settings.
+//!
+//! These settings are controlled by the `MALLOC_CONF` environment variable.
+
+option! {
+    lg_prof_interval[ str: b"opt.lg_prof_interval\0", non_str: 2 ] => libc::ssize_t |
+    ops: r |
+    docs:
+    /// Average interval (log base 2) between memory profile dumps, as measured in bytes of
+    /// allocation activity.
+    ///
+    /// The actual interval between dumps may be sporadic because
+    /// decentralized allocation counters are used to avoid synchronization bottlenecks.
+    ///
+    /// Profiles are dumped to files named according to the pattern
+    /// \<prefix\>.\<pid\>.\<seq\>.i\<iseq\>.heap, where \<prefix\> is controlled by the
+    /// opt.prof_prefix and prof.prefix options. By default, interval-triggered profile dumping is
+    /// disabled (encoded as -1).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[global_allocator]
+    /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+    /// #
+    /// # fn main() {
+    /// use tikv_jemalloc_ctl::profiling;
+    /// let lg_prof_interval = profiling::lg_prof_interval::read().unwrap();
+    /// println!("average interval between memory profile dumps: {}", lg_prof_interval);
+    /// # }
+    /// ```
+    mib_docs: /// See [`lg_prof_interval`].
+}
+
+option! {
+    lg_prof_sample[ str: b"opt.lg_prof_sample\0", non_str: 2 ] => libc::size_t |
+    ops: r |
+    docs:
+    /// Average interval (log base 2) between allocation samples, as measured in bytes of
+    /// allocation activity. Increasing the sampling interval decreases profile fidelity, but also
+    /// decreases the computational overhead.
+    ///
+    /// The default sample interval is 512 KiB (2^19 B).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[global_allocator]
+    /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+    /// #
+    /// # fn main() {
+    /// use tikv_jemalloc_ctl::profiling;
+    /// let lg_prof_sample = profiling::lg_prof_sample::read().unwrap();
+    /// println!("average interval between allocation samples: {}", lg_prof_sample);
+    /// # }
+    /// ```
+    mib_docs: /// See [`lg_prof_sample`].
+}
+
+option! {
+    prof_final[ str: b"opt.prof_final\0", non_str: 2 ] => bool |
+    ops: r |
+    docs:
+    /// Use an atexit(3) function to dump final memory usage to a file named according to the
+    /// pattern \<prefix\>.\<pid\>.\<seq\>.f.heap, where \<prefix\> is controlled by the opt.prof_prefix
+    /// and prof.prefix options.
+    ///
+    /// Note that atexit() may allocate memory during application initialization and then deadlock
+    /// internally when jemalloc in turn calls `atexit()`, so this option is not universally usable
+    /// (though the application can register its own `atexit()` function with equivalent
+    /// functionality).
+    ///
+    /// This option is disabled by default.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[global_allocator]
+    /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+    /// #
+    /// # fn main() {
+    /// use tikv_jemalloc_ctl::profiling;
+    /// let prof_final = profiling::prof_final::read().unwrap();
+    /// println!("dump final memory usage to file: {}", prof_final);
+    /// # }
+    /// ```
+    mib_docs: /// See [`prof_final`].
+}
+
+option! {
+    prof[ str: b"opt.prof\0", non_str: 2 ] => bool |
+    ops: r |
+    docs:
+    /// Memory profiling enabled/disabled.
+    ///
+    /// If enabled, profile memory allocation activity.
+    ///
+    /// See the `opt.prof_active` option for on-the-fly activation/deactivation.
+    ///
+    /// See the `opt.lg_prof_sample` option for probabilistic sampling control.
+    ///
+    /// See the `opt.prof_accum` option for control of cumulative sample reporting.
+    ///
+    /// See the `opt.lg_prof_interval` option for information on interval-triggered profile
+    /// dumping, the `opt.prof_gdump` option for information on high-water-triggered profile
+    /// dumping, and the `opt.prof_final` option for final profile dumping.
+    ///
+    /// Profile output is compatible with the jeprof command, which is based on the pprof that is
+    /// developed as part of the gperftools package. See `HEAP PROFILE FORMAT` for heap profile
+    /// format documentation.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[global_allocator]
+    /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+    /// #
+    /// # fn main() {
+    /// use tikv_jemalloc_ctl::profiling;
+    /// let prof = profiling::prof::read().unwrap();
+    /// println!("is memory profiling enabled: {}", prof);
+    /// # }
+    /// ```
+    mib_docs: /// See [`prof`].
+}
+
+option! {
+    prof_leak[ str: b"opt.prof_leak\0", non_str: 2 ] => bool |
+    ops: r |
+    docs:
+    /// Leak reporting enabled/disabled.
+    ///
+    /// If enabled, use an `atexit(3)` function to report memory leaks detected by allocation
+    /// sampling.
+    ///
+    /// See the opt.prof option for information on analyzing heap profile output.
+    ///
+    /// Works only when combined with `opt.prof_final`, otherwise does nothing.
+    ///
+    /// This option is disabled by default.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # #[global_allocator]
+    /// # static ALLOC: tikv_jemallocator::Jemalloc = tikv_jemallocator::Jemalloc;
+    /// #
+    /// # fn main() {
+    /// use tikv_jemalloc_ctl::profiling;
+    /// let prof_leak = profiling::prof_leak::read().unwrap();
+    /// println!("is leak reporting enabled: {}", prof_leak);
+    /// # }
+    /// ```
+    mib_docs: /// See [`prof_leak`].
+}