Feature flags of MMTk crate // Lib.rs

Cargo Features

[dependencies]
mmtk = { version = "0.29.0", default-features = false, features = ["builtin_env_logger", "nightly", "perf_counter", "mock_test", "test_private", "vm_space", "set_unlog_bits_vm_space", "ro_space", "code_space", "exec_permission_on_all_spaces", "vo_bit", "is_mmtk_object", "object_pinning", "immix_non_moving", "sticky_immix_non_moving_nursery", "immix_stress_copying", "immix_smaller_block", "immix_zero_on_release", "sanity", "analysis", "nogc_lock_free", "nogc_no_zeroing", "single_worker", "extreme_assertions", "nogc_multi_space", "work_packet_stats", "malloc_counted_size", "count_live_bytes_in_gc", "bpftrace_workaround", "malloc_mimalloc", "malloc_jemalloc", "malloc_native_mimalloc", "eager_sweeping", "malloc_mark_sweep"] }

default = builtin_env_logger: The builtin_env_logger feature is set by default whenever mmtk is added without default-features = false somewhere in the dependency tree.
builtin_env_logger default: Built-in env_logger. This feature is enabled by default. The user can disable this default feature to remove env_logger from the dependencies. See crate::util::logger for more details.

Enables env_logger
nightly: Enable this feature if you want to use nightly features and compiler
perf_counter: This feature is only supported on x86-64 for now
It's manually added to CI scripts

Enables pfm
mock_test = test_private: This feature is only used for tests with MockVM.
CI scripts run those tests with this feature.

Affects test_util::fixtures, test_util::mock_method, test_util::mock_vm…
test_private mock_test?: This feature will expose some private functions for testings or benchmarking.

Affects util::test_private…
vm_space: .github/scripts/ci-common.sh extracts features from the following part (including from comments). So be careful when editing or adding stuff to the section below.

Do not modify the following line - ci-common.sh matches it -- Non mutually exclusive features --

spaces with different semantics

A VM-allocated/managed space. A binding could use this for their boot image, metadata space, etc. FIXME: This is not properly implemented yet (it is only working for JikesRVM): https://github.com/mmtk/mmtk-core/issues/415 If a binding would need to trace/scan objects that is allocated and managed by the VM, ActivePlan::vm_trace_object() is an alternative.

Affects memory_manager::set_vm_space, global::BasePlan.vm_space, policy::vmspace…
set_unlog_bits_vm_space: Bulk set unlog bits for all objects inside the VM space. A binding can use this in case they do not have a way to iterate through objects in the bootimage to set the unlog bit. Note that this will set the unlog bit for addresses that may not correspond to valid objects.
ro_space: A readonly space.
TODO: This is not properly implemented yet. We currently use an immortal space instead, and do not guarantee read-only semantics.

Affects global::BasePlan.ro_space…
code_space: A code space with execution permission.

Affects global::BasePlan.code_space, global::BasePlan.code_lo_space…
exec_permission_on_all_spaces: By default, we only allow execution permission for code spaces. With this feature, all the spaces have execution permission.
Use with care.
vo_bit is_mmtk_object? = eager_sweeping: Global valid object (VO) bit metadata. The VO bit is set when an object is allocated, and cleared when the GC determines it is dead. See src/util/metadata/vo_bit/mod.rs

eager_sweeping: VO bits for dead objects must have been cleared by the end of each GC. Native MarkSweep only ensures this in eager sweeping mode.

Affects immixspace::ImmixSpaceArgs.mixed_age…
is_mmtk_object = vo_bit: conservative garbage collection support

Affects memory_manager::is_mmtk_object, memory_manager::find_object_from_internal_pointer, metadata::has_object_alloced_by_malloc, sft::SFT.is_mmtk_object, sft::SFT.find_object_from_internal_pointer, util::is_mmtk_object…
object_pinning: Enable object pinning, in particular, enable pinning/unpinning, and its metadata

Affects memory_manager::pin_object, memory_manager::unpin_object, memory_manager::is_pinned, sft::SFT.pin_object, sft::SFT.unpin_object, sft::SFT.is_object_pinned…
immix_non_moving: The following two features are useful for using Immix for VMs that do not support moving GC.

Disable any object copying in Immix. This makes Immix a non-moving policy.
sticky_immix_non_moving_nursery: Disable any object copying in nursery GC for Sticky Immix while allowing other kinds of copying. immix_non_moving disables all kinds of copying in Immix, so this feature is not needed if immix_non_moving is in use.
immix_stress_copying: Turn on stress copying for Immix. This is a debug feature to test copying for Immix plans.
immix_smaller_block: Reduce block size for ImmixSpace. This mitigates fragmentation when defrag is disabled.
immix_zero_on_release: Zero the unmarked lines after a GC cycle in immix. This helps debug untraced objects.
sanity: Run sanity GC

Affects sft::SFT.is_sane, gc_work::ProcessEdgesWork.cache_roots_for_sanity_gc…
analysis: Run analysis

Affects allocator::AllocatorContext.analysis_manager…
nogc_lock_free nogc_no_zeroing?: Use lock free variant of NoGC
nogc_no_zeroing = nogc_lock_free: Use lock free with no zeroing NoGC
single_worker: For using a single GC thread
Q: Why do we need this as a compile time flat? We can always set the number of GC threads through options.
extreme_assertions: To run expensive comprehensive runtime checks, such as checking duplicate edges

Affects sanity::verify_bzero, sanity::verify_bset, sanity::verify_bcopy, sanity::verify_load, sanity::verify_store, sanity::verify_update…
nogc_multi_space: Enable multiple spaces for NoGC, each allocator maps to an individual ImmortalSpace.
work_packet_stats: To collect statistics for each GC work packet. Enabling this may introduce a small overhead (several percentage slowdown on benchmark time).
malloc_counted_size: Count the malloc'd memory into the heap size

Affects memory_manager::counted_malloc, memory_manager::counted_calloc, memory_manager::realloc_with_old_size, memory_manager::free_with_size, memory_manager::get_malloc_bytes, malloc::counted_malloc, malloc::counted_calloc, malloc::realloc_with_old_size, malloc::free_with_size…
count_live_bytes_in_gc: Count the size of all live objects in GC

Affects memory_manager::live_bytes_in_last_gc…
bpftrace_workaround: Workaround a problem where bpftrace scripts (see tools/tracing/timeline/capture.bt) cannot capture the type names of work packets.
malloc_mimalloc: Do not modify the following line - ci-common.sh matches it -- Mutally exclusive features --
Only one feature from each group can be provided. Otherwise build will fail.

Name of the mutualy exclusive feature group. ci-common.sh matches lines like this one.
Group:malloc
only one of the following features should be enabled, or none to use the default malloc from libc this does not replace the global Rust allocator, but provides these libraries for GC implementation

Enables mimalloc-sys
malloc_jemalloc: Enables jemalloc-sys
malloc_native_mimalloc: Use the native mimalloc allocator for malloc. This is not tested by me (Yi) yet, and it is only used to make sure that some code is not compiled in default builds.
eager_sweeping vo_bit?: If there are more groups, they should be inserted above this line Group:end

Group:marksweepallocation
default is native allocator with lazy sweeping
malloc_mark_sweep: Use library malloc as the freelist allocator for mark sweep. This will makes mark sweep slower. As malloc may return addresses outside our normal heap range, we will have to use chunk-based SFT table. Turning on this feature will use a different SFT map implementation on 64bits,
and will affect all the plans in the build. Please be aware of the consequence, and this is only meant to be experimental use.

Affects global::MarkSweepSpace…