mmtk/scheduler/
work.rs

1use super::worker::*;
2use crate::mmtk::MMTK;
3use crate::vm::VMBinding;
4#[cfg(feature = "work_packet_stats")]
5use std::any::{type_name, TypeId};
6
7/// This defines a GC work packet which are assigned to the [`GCWorker`]s by the scheduler.
8/// Work packets carry payloads that indicate the work to be done. For example, a work packet may
9/// contain a pointer to a stack that must be scanned, or it may contain a large buffer of pointers
10/// that need to be traced, or it might contain a range of static variables to be scanned, etc. The size
11/// of the work packet will need to consider at least two points of tension: the work packet must be large
12/// enough to ensure that the costs of managing the work packets do not dominate, and the packet must be
13/// small enough that good load balancing is achieved.
14pub trait GCWork<VM: VMBinding>: 'static + Send {
15    /// Define the work for this packet. However, this is not supposed to be called directly.
16    /// Usually `do_work_with_stat()` should be used.
17    ///
18    /// Most work packets are polled and executed in the worker's main loop ([`GCWorker::run`])
19    /// using `do_work_with_stat`.  If `do_work` is called directly during the execution of another
20    /// work packet, bypassing `do_work_with_stat()`, this work packet will not be counted into the
21    /// number of work packets executed, and the execution time of this work packet will be counted
22    /// as part of the execution time of the other work packet.  Only call this method directly if
23    /// this is what you intend.  But you should always consider adding the work packet
24    /// into a bucket so that other GC workers can execute it in parallel, unless the context-
25    /// switching overhead is a problem.
26    fn do_work(&mut self, worker: &mut GCWorker<VM>, mmtk: &'static MMTK<VM>);
27
28    /// Do work and collect statistics. This internally calls `do_work()`. In most cases,
29    /// this should be called rather than `do_work()` so that MMTk can correctly collect
30    /// statistics for the work packets.
31    /// If the feature "work_packet_stats" is not enabled, this call simply forwards the call
32    /// to `do_work()`.
33    fn do_work_with_stat(&mut self, worker: &mut GCWorker<VM>, mmtk: &'static MMTK<VM>) {
34        debug!("{}", std::any::type_name::<Self>());
35        debug_assert!(!worker.tls.0.0.is_null(), "TLS must be set correctly for a GC worker before the worker does any work. GC Worker {} has no valid tls.", worker.ordinal);
36
37        #[cfg(feature = "work_packet_stats")]
38        // Start collecting statistics
39        let stat = {
40            let mut worker_stat = worker.shared.borrow_stat_mut();
41            worker_stat.measure_work(TypeId::of::<Self>(), type_name::<Self>(), mmtk)
42        };
43
44        // Do the actual work
45        self.do_work(worker, mmtk);
46
47        #[cfg(feature = "work_packet_stats")]
48        // Finish collecting statistics
49        {
50            let mut worker_stat = worker.shared.borrow_stat_mut();
51            stat.end_of_work(&mut worker_stat);
52        }
53    }
54
55    /// Get the compile-time static type name for the work packet.
56    fn get_type_name(&self) -> &'static str {
57        std::any::type_name::<Self>()
58    }
59}
60
61use super::gc_work::ProcessEdgesWork;
62use crate::plan::Plan;
63
64/// This trait provides a group of associated types that are needed to
65/// create GC work packets for a certain plan. For example, `GCWorkScheduler.schedule_common_work()`
66/// needs this trait to schedule different work packets. For certain plans,
67/// they may need to provide several types that implement this trait, e.g. one for
68/// nursery GC, one for mature GC.
69///
70/// Note: Because `GCWorkContext` is often used as parameters of implementations of `GCWork`, we
71/// let GCWorkContext require `Send + 'static`.  Since `GCWorkContext` is just a group of
72/// associated types, its implementations should not have any actual fields other than
73/// `PhantomData`, and will automatically have `Send + 'static`.
74pub trait GCWorkContext: Send + 'static {
75    type VM: VMBinding;
76    type PlanType: Plan<VM = Self::VM>;
77
78    // FIXME: We should use `SFTProcessEdges` as the default value for `DefaultProcessEdges`, and
79    // `UnsupportedProcessEdges` for `PinningProcessEdges`.  However, this requires
80    // `associated_type_defaults` which has not yet been stablized.
81    // See: https://github.com/rust-lang/rust/issues/29661
82
83    /// The `ProcessEdgesWork` implementation to use for tracing edges that do not have special
84    /// pinning requirements.  Concrete plans and spaces may choose to move or not to move the
85    /// objects the traced edges point to.
86    type DefaultProcessEdges: ProcessEdgesWork<VM = Self::VM>;
87
88    /// The `ProcessEdgesWork` implementation to use for tracing edges that must not be updated
89    /// (i.e. the objects the traced edges pointed to must not be moved).  This is used for
90    /// implementing pinning roots and transitive pinning roots.
91    ///
92    /// -   For non-transitive pinning roots, `PinningProcessEdges` will be used to trace the edges
93    ///     from roots to objects, but their descendents will be traced using `DefaultProcessEdges`.
94    /// -   For transitive pinning roots, `PinningProcessEdges` will be used to trace the edges
95    ///     from roots to objects, and will also be used to trace the outgoing edges of all objects
96    ///     reachable from transitive pinning roots.
97    ///
98    /// If a plan does not support object pinning, it should use `UnsupportedProcessEdges` for this
99    /// type member.
100    type PinningProcessEdges: ProcessEdgesWork<VM = Self::VM>;
101}
mmtk/scheduler/work.rs

mmtk/scheduler/
work.rs
