sandpit 0.5.2

A concurrent garbage collected arena
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

/// This structure contains the configuration settings for a garbage collector.
#[derive(Copy, Clone, Debug)]
pub struct Config {
    /// The number of tracer threads, not including the thread that is used for
    /// monitoring.
    pub tracer_threads: usize,
    /// The amount of work a tracer does before attempting to share its work.
    pub trace_chunk_size: usize,
    /// The minimum a mount of work a tracer must obtain in order to share its work.
    pub trace_share_min: usize,
    /// The percent of work a tracer shares when sharing its work.
    pub trace_share_ratio: f32,
    /// The amount of miliseconds a tracer will wait for work before checking again or finishing its trace.
    pub trace_wait_time: u64,

    /// Once the amount of marked objects surpasses the max old object count
    /// a major collection will be triggered. The max old object count is calculated
    /// by multiplying this value by the amount of old objects marked in the
    /// previous major collection.
    pub monitor_max_old_growth_rate: f32,
    /// Once the size of the arena divided by the previous arena size after collection
    /// surpassed this value, a minor collection will be triggered.
    pub monitor_arena_size_ratio_trigger: f32,
    /// This setting this flag on or off will enable the monitor respectively.
    pub monitor_wait_time: u64,
    pub monitor_on: bool,

    /// The minimum amount of work a mutator must accumulate before sending to
    /// be traced.
    pub mutator_share_min: usize,

    /// The headroom is the maximum amount of memory that can be allocated,
    /// during a collection, before a yield is requested.
    /// The headroom is calculated by multiplying the previous arena size by
    /// the headroom ratio.
    pub collector_max_headroom_ratio: f64,

    /// The timeslicer essentially rate limits aggressive mutators, to ensure
    /// that the tracers will outpace them. The timeslice size will effect the
    /// length of time the timeslicer will request a mutator to yield in a single
    /// time frame. This represent number represents milliseconds.
    pub collector_timeslice_size: f64,

    /// The minimum amount of time the timeslicer will request yields for.
    /// Lowering this may help less aggressive mutators, but might make more
    /// aggressive mutators more likely to trigger yield earlier in the tracing
    /// process (meaning less concurrency).
    /// This represent number represents milliseconds.
    pub collector_slice_min: f64,
}

pub const GC_CONFIG_DEFAULT_TRACE_THREADS: usize = 2;
pub const GC_CONFIG_DEFAULT_TRACE_CHUNK_SIZE: usize = 100;
pub const GC_CONFIG_DEFAULT_TRACE_SHARE_MIN: usize = 50;
pub const GC_CONFIG_DEFAULT_TRACE_SHARE_RATIO: f32 = 0.5;
pub const GC_CONFIG_DEFAULT_TRACE_WAIT_TIME: u64 = 1;

// basically all the heuristic constant values used in this crate are collected here
// not necessarily a good idea to change any of these, but collecting them all here
// at least makes it clear what values are "arbitrary"
//
// The Config can be updated after the Gc is created, but the update will only take place
// until tracing has completed.
impl Config {
    /// Creates a default Config. Good for most use cases.
    pub fn default() -> Self {
        Config {
            tracer_threads: GC_CONFIG_DEFAULT_TRACE_THREADS,
            trace_chunk_size: GC_CONFIG_DEFAULT_TRACE_CHUNK_SIZE,
            trace_share_min: GC_CONFIG_DEFAULT_TRACE_SHARE_MIN,
            trace_share_ratio: GC_CONFIG_DEFAULT_TRACE_SHARE_RATIO,
            trace_wait_time: GC_CONFIG_DEFAULT_TRACE_WAIT_TIME,

            monitor_max_old_growth_rate: 1.5,
            monitor_arena_size_ratio_trigger: 1.5,
            monitor_wait_time: 10,
            monitor_on: true,

            mutator_share_min: 1000,

            collector_max_headroom_ratio: 0.5,
            collector_timeslice_size: 2.0,
            collector_slice_min: 0.6,
        }
    }
}