@@ -45,6 +45,11 @@ use parking_lot::Mutex;
4545use super :: { MemoryConsumer , MemoryLimit , MemoryPool , MemoryReservation } ;
4646
4747/// Returns the number of bytes currently allocated by the process.
48+ ///
49+ /// This is called on every reservation change (`grow`, `try_grow` and
50+ /// `shrink`) of every pool that reports to the tracker, so it must be cheap,
51+ /// e.g. a single atomic load. Do not read allocator statistics that need a
52+ /// refresh on each call (such as jemalloc's `epoch`).
4853pub type AllocatedBytesFn = Arc < dyn Fn ( ) -> usize + Send + Sync > ;
4954
5055/// Default rise in drift, in bytes, needed before another line is logged.
@@ -99,9 +104,14 @@ pub struct MemoryDriftTracker {
99104/// One observation of drift, recorded by [`MemoryDriftTracker`].
100105#[ derive( Debug , Clone , PartialEq , Eq ) ]
101106pub struct DriftSample {
102- /// Label of the [`DriftLoggingPool`] that made the observation.
107+ /// Label of the [`DriftLoggingPool`] whose reservation change took this
108+ /// sample, or the source passed to [`MemoryDriftTracker::sample`]. When
109+ /// several pools share a tracker, the untracked memory can come from any
110+ /// of them.
103111 pub pool : String ,
104- /// Consumer whose reservation change triggered the observation.
112+ /// Consumer whose reservation change took this sample (empty for
113+ /// [`MemoryDriftTracker::sample`]). This shows when drift was sampled,
114+ /// not what caused it.
105115 pub consumer : String ,
106116 /// Bytes reserved across all pools reporting to the tracker.
107117 pub reserved : usize ,
@@ -159,6 +169,17 @@ impl MemoryDriftTracker {
159169 self . peak . lock ( ) . clone ( )
160170 }
161171
172+ /// Compare the current allocated bytes with the reserved total now,
173+ /// without a reservation change.
174+ ///
175+ /// Drift is otherwise only sampled when a reservation changes, so memory
176+ /// allocated by code that reserves little can go unseen until some other
177+ /// reservation changes. Calling this periodically, e.g. from a timer,
178+ /// closes that gap. `source` is recorded as the pool label.
179+ pub fn sample ( & self , source : & str ) {
180+ self . observe ( source, "" , self . reserved ( ) ) ;
181+ }
182+
162183 fn grew ( & self , pool : & str , consumer : & str , additional : usize ) {
163184 let reserved =
164185 self . reserved . fetch_add ( additional, Ordering :: Relaxed ) + additional;
@@ -170,7 +191,8 @@ impl MemoryDriftTracker {
170191 self . observe ( pool, consumer, reserved) ;
171192 }
172193
173- fn observe ( & self , pool : & str , consumer : & str , reserved : usize ) {
194+ /// Returns `true` if a line was logged.
195+ fn observe ( & self , pool : & str , consumer : & str , reserved : usize ) -> bool {
174196 let allocated = ( self . allocated ) ( ) ;
175197 let drift = allocated as isize - reserved as isize ;
176198
@@ -198,15 +220,17 @@ impl MemoryDriftTracker {
198220 let last = self . last_logged . load ( Ordering :: Relaxed ) ;
199221 let rose = untracked >= last. saturating_add ( self . log_threshold as isize ) ;
200222 if !rose && untracked >= last {
201- return ;
223+ return false ;
202224 }
203225 let updated = self
204226 . last_logged
205227 . compare_exchange ( last, untracked, Ordering :: Relaxed , Ordering :: Relaxed )
206228 . is_ok ( ) ;
207- if updated && rose {
229+ let logged = updated && rose;
230+ if logged {
208231 log:: info!( "memory drift: {}" , sample( ) ) ;
209232 }
233+ logged
210234 }
211235}
212236
@@ -421,6 +445,65 @@ mod tests {
421445 ) ;
422446 }
423447
448+ #[ test]
449+ fn logs_each_rise_by_the_threshold_and_rearms_after_a_fall ( ) {
450+ let allocated = Arc :: new ( AtomicUsize :: new ( 0 ) ) ;
451+ let source = Arc :: clone ( & allocated) ;
452+ let tracker =
453+ MemoryDriftTracker :: new ( Arc :: new ( move || source. load ( Ordering :: Relaxed ) ) )
454+ . with_log_threshold ( 1000 ) ;
455+ let observe = |bytes : usize | {
456+ allocated. store ( bytes, Ordering :: Relaxed ) ;
457+ tracker. observe ( "p" , "c" , 0 )
458+ } ;
459+
460+ // Below the threshold: nothing logged.
461+ assert ! ( !observe( 999 ) ) ;
462+ // Reaching the threshold logs and moves the baseline to 1000.
463+ assert ! ( observe( 1000 ) ) ;
464+ assert ! ( !observe( 1999 ) ) ;
465+ assert ! ( observe( 2000 ) ) ;
466+ // Falling drift is not logged but lowers the baseline to 500...
467+ assert ! ( !observe( 500 ) ) ;
468+ // ...so a rise of the threshold from there logs again.
469+ assert ! ( !observe( 1499 ) ) ;
470+ assert ! ( observe( 1500 ) ) ;
471+ }
472+
473+ #[ test]
474+ fn negative_drift_counts_as_zero_for_logging ( ) {
475+ let ( allocated, tracker) = tracker ( ) ;
476+ let tracker = Arc :: into_inner ( tracker) . unwrap ( ) . with_log_threshold ( 1000 ) ;
477+
478+ assert ! ( !tracker. observe( "p" , "c" , 5000 ) ) ;
479+ allocated. store ( 999 , Ordering :: Relaxed ) ;
480+ assert ! ( !tracker. observe( "p" , "c" , 0 ) ) ;
481+ allocated. store ( 1000 , Ordering :: Relaxed ) ;
482+ assert ! ( tracker. observe( "p" , "c" , 0 ) ) ;
483+ }
484+
485+ #[ test]
486+ fn sample_observes_without_a_reservation_change ( ) {
487+ let ( allocated, tracker) = tracker ( ) ;
488+ let pool = pool ( & tracker, "q1" ) ;
489+ let reservation = MemoryConsumer :: new ( "a" ) . register ( & pool) ;
490+ reservation. grow ( 100 ) ;
491+
492+ allocated. store ( 5000 , Ordering :: Relaxed ) ;
493+ tracker. sample ( "timer" ) ;
494+
495+ assert_eq ! (
496+ tracker. peak_drift( ) ,
497+ Some ( DriftSample {
498+ pool: "timer" . to_string( ) ,
499+ consumer: String :: new( ) ,
500+ reserved: 100 ,
501+ allocated: 5000 ,
502+ drift: 4900 ,
503+ } )
504+ ) ;
505+ }
506+
424507 #[ test]
425508 fn delegates_to_the_wrapped_pool ( ) {
426509 let ( _allocated, tracker) = tracker ( ) ;
0 commit comments