Struct HashSet

pub struct HashSet<K, S = RandomState> { /* private fields */ }

A concurrent hash set.

Most hash set operations require a Guard, which can be acquired through HashSet::guard or using the HashSet::pin API. See the crate-level documentation for details.

Implementations

impl<K> HashSet<K>

pub fn new() -> HashSet<K>

Creates an empty HashSet.

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

Examples

use papaya::HashSet;
let map: HashSet<&str> = HashSet::new();

pub fn with_capacity(capacity: usize) -> HashSet<K>

Creates an empty HashSet with the specified capacity.

The set should be able to hold at least capacity elements before resizing. However, the capacity is an estimate, and the set may prematurely resize due to poor hash distribution. If capacity is 0, the hash set will not allocate.

Examples

use papaya::HashSet;
let set: HashSet<&str> = HashSet::with_capacity(10);

pub fn builder() -> HashSetBuilder<K>

Returns a builder for a HashSet.

The builder can be used for more complex configuration, such as using a custom Collector, or ResizeMode.

impl<K, S> HashSet<K, S>

pub fn with_hasher(hash_builder: S) -> HashSet<K, S>

Creates an empty HashSet which will use the given hash builder to hash keys.

Warning: hash_builder is normally randomly generated, and is designed to allow HashSets 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 HashSet to be useful, see its documentation for details.

Examples

use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_hasher(s);
set.pin().insert(1);

pub fn with_capacity_and_hasher( capacity: usize, hash_builder: S, ) -> HashSet<K, S>

Creates an empty HashSet with at least the specified capacity, using hash_builder to hash the keys.

The set should be able to hold at least capacity elements before resizing. However, the capacity is an estimate, and the set may prematurely resize due to poor hash distribution. If capacity is 0, the hash set will not allocate.

Warning: hash_builder is normally randomly generated, and is designed to allow HashSets 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 hasher passed should implement the BuildHasher trait for the HashSet to be useful, see its documentation for details.

Examples

use papaya::HashSet;
use std::hash::RandomState;

let s = RandomState::new();
let set = HashSet::with_capacity_and_hasher(10, s);
set.pin().insert(1);

pub fn pin(&self) -> HashSetRef<'_, K, S, LocalGuard<'_>>

Returns a pinned reference to the set.

The returned reference manages a guard internally, preventing garbage collection for as long as it is held. See the crate-level documentation for details.

pub fn pin_owned(&self) -> HashSetRef<'_, K, S, OwnedGuard<'_>>

Returns a pinned reference to the set.

Unlike HashSet::pin, the returned reference implements Send and Sync, allowing it to be held across .await points in work-stealing schedulers. This is especially useful for iterators.

The returned reference manages a guard internally, preventing garbage collection for as long as it is held. See the crate-level documentation for details.

pub fn guard(&self) -> LocalGuard<'_>

Returns a guard for use with this set.

Note that holding on to a guard prevents garbage collection. See the crate-level documentation for details.

pub fn owned_guard(&self) -> OwnedGuard<'_>

Returns an owned guard for use with this set.

Owned guards implement Send and Sync, allowing them to be held across .await points in work-stealing schedulers. This is especially useful for iterators.

Note that holding on to a guard prevents garbage collection. See the crate-level documentation for details.

impl<K, S> HashSet<K, S>

where K: Hash + Eq, S: BuildHasher,

pub fn len(&self) -> usize

Returns the number of entries in the set.

Examples

use papaya::HashSet;

let set = HashSet::new();

set.pin().insert(1);
set.pin().insert(2);
assert!(set.len() == 2);

pub fn is_empty(&self) -> bool

Returns true if the set is empty. Otherwise returns false.

Examples

use papaya::HashSet;

let set = HashSet::new();
assert!(set.is_empty());
set.pin().insert("a");
assert!(!set.is_empty());

pub fn contains<Q>(&self, key: &Q, guard: &impl Guard) -> bool

where Q: Equivalent<K> + Hash + ?Sized,

Returns true if the set contains a value for the specified key.

The key may be any borrowed form of the set’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use papaya::HashSet;

let set = HashSet::new();
set.pin().insert(1);
assert_eq!(set.pin().contains(&1), true);
assert_eq!(set.pin().contains(&2), false);

pub fn get<'g, Q>(&self, key: &Q, guard: &'g impl Guard) -> Option<&'g K>

where Q: Equivalent<K> + Hash + ?Sized,

Returns a reference to the value corresponding to the key.

The key may be any borrowed form of the set’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use papaya::HashSet;

let set = HashSet::new();
set.pin().insert(1);
assert_eq!(set.pin().get(&1), Some(&1));
assert_eq!(set.pin().get(&2), None);

pub fn insert(&self, key: K, guard: &impl Guard) -> bool

Inserts a value into the set.

If the set did not have this key present, true is returned.

If the set did have this key present, false is returned and the old value is not updated. This matters for types that can be == without being identical. See the standard library documentation for details.

Examples

use papaya::HashSet;

let set = HashSet::new();
assert_eq!(set.pin().insert(37), true);
assert_eq!(set.pin().is_empty(), false);

set.pin().insert(37);
assert_eq!(set.pin().insert(37), false);
assert_eq!(set.pin().get(&37), Some(&37));

pub fn remove<Q>(&self, key: &Q, guard: &impl Guard) -> bool

where Q: Equivalent<K> + Hash + ?Sized,

Removes a key from the set, returning the value at the key if the key was previously in the set.

The key may be any borrowed form of the set’s key type, but Hash and Eq on the borrowed form must match those for the key type.

Examples

use papaya::HashSet;

let set = HashSet::new();
set.pin().insert(1);
assert_eq!(set.pin().remove(&1), true);
assert_eq!(set.pin().remove(&1), false);

pub fn reserve(&self, additional: usize, guard: &impl Guard)

Tries to reserve capacity for additional more elements to be inserted in the HashSet.

After calling this method, the set should be able to hold at least capacity elements before resizing. However, the capacity is an estimate, and the set may prematurely resize due to poor hash distribution. The collection may also reserve more space to avoid frequent reallocations.

Panics

Panics if the new allocation size overflows usize.

Examples

use papaya::HashSet;

let set: HashSet<&str> = HashSet::new();
set.pin().reserve(10);

pub fn clear(&self, guard: &impl Guard)

Clears the set, removing all values.

Note that this method will block until any in-progress resizes are completed before proceeding. See the consistency section for details.

Examples

use papaya::HashSet;

let set = HashSet::new();

set.pin().insert(1);
set.pin().clear();
assert!(set.pin().is_empty());

pub fn retain<F>(&mut self, f: F, guard: &impl Guard)

where F: FnMut(&K) -> bool,

Retains only the elements specified by the predicate.

In other words, remove all values v for which f(&v) returns false. The elements are visited in unsorted (and unspecified) order.

Note the function may be called more than once for a given key if its value is concurrently modified during removal.

Additionally, this method will block until any in-progress resizes are completed before proceeding. See the consistency section for details.

Examples

use papaya::HashSet;

let mut set: HashSet<i32> = (0..8).collect();
set.pin().retain(|&v| v % 2 == 0);
assert_eq!(set.len(), 4);
assert_eq!(set.pin().contains(&1), false);
assert_eq!(set.pin().contains(&2), true);

pub fn iter<'g, G>(&self, guard: &'g G) -> Iter<'g, K, G>

where G: Guard,

An iterator visiting all values in arbitrary order.

Note that this method will block until any in-progress resizes are completed before proceeding. See the consistency section for details.

Examples

use papaya::HashSet;

let set = HashSet::from([
    "a",
    "b",
    "c"
]);

for val in set.pin().iter() {
    println!("val: {val}");
}

Trait Implementations

impl<K, S> Clone for HashSet<K, S>

where K: Clone + Hash + Eq, S: BuildHasher + Clone,

fn clone(&self) -> HashSet<K, S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<K, S> Debug for HashSet<K, S>

where K: Hash + Eq + Debug, S: BuildHasher,

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

Formats the value using the given formatter.

impl<K, S> Default for HashSet<K, S>

where S: Default,

fn default() -> Self

Returns the “default value” for a type.

impl<'a, K, S> Extend<&'a K> for &HashSet<K, S>

where K: Copy + Hash + Eq + 'a, S: BuildHasher,

fn extend<T: IntoIterator<Item = &'a K>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, S> Extend<K> for &HashSet<K, S>

where K: Hash + Eq, S: BuildHasher,

fn extend<T: IntoIterator<Item = K>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<K, const N: usize> From<[K; N]> for HashSet<K, RandomState>

where K: Hash + Eq,

fn from(arr: [K; N]) -> Self

Converts to this type from the input type.

impl<K, S> FromIterator<K> for HashSet<K, S>

where K: Hash + Eq, S: BuildHasher + Default,

fn from_iter<T: IntoIterator<Item = K>>(iter: T) -> Self

Creates a value from an iterator.

impl<K, S> PartialEq for HashSet<K, S>

where K: Hash + Eq, S: BuildHasher,

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<K, S> Eq for HashSet<K, S>

where K: Hash + Eq, S: BuildHasher,

impl<K: Send, S: Send> Send for HashSet<K, S>

impl<K: Sync, S: Sync> Sync for HashSet<K, S>