Struct LoadedFeatures

pub struct LoadedFeatures<S = RandomState> { /* private fields */ }

A set of all sources loaded by a Ruby interpreter with require and require_relative.

In Ruby, when loading files with require and require_relative, the constants defined in them have global scope. Ruby keeps track of loaded sources in its interpreter state to ensure files are not require’d multiple times.

Ruby refers to files tracked in this way as features. The set of loaded features are stored in a global variable called $LOADED_FEATURES, which is aliased to $".

$LOADED_FEATURES is an append only set. Disk-based features are deduplicated by their real position on the underlying file system (i.e. their device and inode).

Ruby uses a feature’s presence in the loaded features set to determine whether a require has side effects (i.e. a file can be required multiple times but is only evaluated once).

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
features.insert(Feature::with_in_memory_path("/src/_lib/test.rb".into()));
features.insert(Feature::with_in_memory_path("set.rb".into()));
features.insert(Feature::with_in_memory_path("artichoke.rb".into()));

for f in features.features() {
    println!("Loaded feature at: {}", f.path().display());
}

features.shrink_to_fit();

Implementations

impl LoadedFeatures<RandomState>

pub fn new() -> Self

Creates an empty LoadedFeatures.

The set of features is initially created with a capacity of 0, so it will not allocate until it is first inserted into.

Examples

use mezzaluna_loaded_features::LoadedFeatures;

let features = LoadedFeatures::new();
assert!(features.is_empty());
assert_eq!(features.capacity(), 0);

pub fn with_capacity(capacity: usize) -> Self

Creates an empty LoadedFeatures with the specified capacity.

The set of features will be able to hold at least capacity elements without reallocating. If capacity is 0, the feature set will not allocate.

Examples

use mezzaluna_loaded_features::LoadedFeatures;

let features = LoadedFeatures::with_capacity(10);
assert!(features.capacity() >= 10);

impl<S> LoadedFeatures<S>

pub fn capacity(&self) -> usize

Returns the number of elements the set of features can hold without reallocating.

Examples

use mezzaluna_loaded_features::LoadedFeatures;

let features = LoadedFeatures::with_capacity(100);
assert!(features.capacity() >= 100);

pub fn iter(&self) -> Iter<'_>

An iterator visiting all features in insertion order. The iterator element type is &'a Path.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
features.insert(Feature::with_in_memory_path("/src/_lib/test.rb".into()));
features.insert(Feature::with_in_memory_path("set.rb".into()));
features.insert(Feature::with_in_memory_path("artichoke.rb".into()));

for path in features.iter() {
    println!("Loaded feature at: {}", path.display());
}

pub fn features(&self) -> Features<'_>

An iterator visiting all features in arbitrary order. The iterator element type is &'a Feature.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
features.insert(Feature::with_in_memory_path("/src/_lib/test.rb".into()));
features.insert(Feature::with_in_memory_path("set.rb".into()));
features.insert(Feature::with_in_memory_path("artichoke.rb".into()));

for f in features.features() {
    println!("Loaded feature at: {}", f.path().display());
}

pub fn len(&self) -> usize

Returns the number of features in the set.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
assert_eq!(features.len(), 0);

features.insert(Feature::with_in_memory_path("/src/_lib/test.rb".into()));
assert_eq!(features.len(), 1);

pub fn is_empty(&self) -> bool

Returns true if the set contains no features.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
assert!(features.is_empty());

features.insert(Feature::with_in_memory_path("/src/_lib/test.rb".into()));
assert!(!features.is_empty());

pub fn with_hasher(hasher: S) -> Self

Creates a new empty feature set which will use the given hasher to hash keys.

The feature set is also created with the default initial capacity.

Warning: hasher is normally randomly generated, and is designed to allow LoadedFeatures to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

The hash_builder passed should implement the BuildHasher trait for the LoadedFeatures to be useful, see its documentation for details.

Examples

use std::collections::hash_map::RandomState;

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let s = RandomState::new();
let mut features = LoadedFeatures::with_hasher(s);
features.insert(Feature::with_in_memory_path("set.rb".into()));

pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> Self

Creates a new empty feature set with the specified capacity which will use the given hasher to hash keys.

The feature set will be able to hold at least capacity elements without reallocating. If capacity is 0, the feature set will not allocate.

Warning: hasher is normally randomly generated, and is designed to allow LoadedFeatures to be resistant to attacks that cause many collisions and very poor performance. Setting it manually using this function can expose a DoS attack vector.

The hash_builder passed should implement the BuildHasher trait for the LoadedFeatures to be useful, see its documentation for details.

Examples

use std::collections::hash_map::RandomState;

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let s = RandomState::new();
let mut features = LoadedFeatures::with_capacity_and_hasher(10, s);
features.insert(Feature::with_in_memory_path("set.rb".into()));

pub fn hasher(&self) -> &S

Returns a reference to the feature set’s BuildHasher.

Examples

use std::collections::hash_map::RandomState;

use mezzaluna_loaded_features::LoadedFeatures;

let s = RandomState::new();
let features = LoadedFeatures::with_hasher(s);
let hasher: &RandomState = features.hasher();

impl<S> LoadedFeatures<S>

where S: BuildHasher,

pub fn reserve(&mut self, additional: usize)

Reserves capacity for at least additional more elements to be inserted in the LoadedFeatures. The collection may reserve more space to avoid frequent reallocations.

Panics

Panics if the new allocation size overflows usize.

Examples

use mezzaluna_loaded_features::LoadedFeatures;

let mut features = LoadedFeatures::new();
features.reserve(10);
assert!(features.capacity() >= 10);

pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError>

Tries to reserve capacity for at least additional more elements to be inserted in the LoadedFeatures. The collection may reserve more space to avoid frequent reallocations. After calling try_reserve, capacity will be greater than or equal to self.len() + additional. Does nothing if capacity is already sufficient.

Errors

If the capacity overflows, or the allocator reports a failure, then an error is returned.

Examples

use mezzaluna_loaded_features::LoadedFeatures;

let mut features = LoadedFeatures::new();
features
    .try_reserve(10)
    .expect("why is this OOMing on 10 features?");
assert!(features.capacity() >= 10);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the set as much as possible. It will drop down as much as possible while maintaining the internal rules and possibly leaving some space in accordance with the resize policy.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::with_capacity(100);
features.insert(Feature::with_in_memory_path("set.rb".into()));
features.insert(Feature::with_in_memory_path("artichoke.rb".into()));

assert!(features.capacity() >= 100);
features.shrink_to_fit();
assert!(features.capacity() >= 2);

pub fn shrink_to(&mut self, min_capacity: usize)

Shrinks the capacity of the set with a lower bound.

The capacity will remain at least as large as both the length and the supplied value.

If the current capacity is less than the lower limit, this is a no-op.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::with_capacity(100);
features.insert(Feature::with_in_memory_path("set.rb".into()));
features.insert(Feature::with_in_memory_path("artichoke.rb".into()));

assert!(features.capacity() >= 100);
features.shrink_to(2);
assert!(features.capacity() >= 2);

pub fn contains(&self, feature: &Feature) -> bool

Returns true if the set contains a feature.

Features loaded from disk are compared based on whether they point to the same file on the underlying file system. Features loaded from memory are compared by their paths.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
let set_feature = Feature::with_in_memory_path("set.rb".into());

assert!(!features.contains(&set_feature));

features.insert(set_feature);
assert_eq!(features.len(), 1);

pub fn insert(&mut self, feature: Feature)

Add a feature to the set.

Panics

Panics if the given feature is already loaded.

Examples

use mezzaluna_loaded_features::{Feature, LoadedFeatures};

let mut features = LoadedFeatures::new();
let set_feature = Feature::with_in_memory_path("set.rb".into());
features.insert(set_feature);

assert_eq!(features.len(), 1);

Trait Implementations

impl<S: Debug> Debug for LoadedFeatures<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for LoadedFeatures

fn default() -> Self

Returns the “default value” for a type.

impl<'a, S> IntoIterator for &'a LoadedFeatures<S>

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

type Item = &'a Path

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.