Trait SortedListProvider

pub trait SortedListProvider<AccountId> {
    type Error: Debug;
    type Score: Bounded + Saturating + Zero + Default;

    // Required methods
    fn iter() -> Box<dyn Iterator<Item = AccountId>>;
    fn lock();
    fn unlock();
    fn iter_from(
        start: &AccountId,
    ) -> Result<Box<dyn Iterator<Item = AccountId>>, Self::Error>;
    fn count() -> u32;
    fn contains(id: &AccountId) -> bool;
    fn on_insert(id: AccountId, score: Self::Score) -> Result<(), Self::Error>;
    fn on_update(id: &AccountId, score: Self::Score) -> Result<(), Self::Error>;
    fn get_score(id: &AccountId) -> Result<Self::Score, Self::Error>;
    fn on_remove(id: &AccountId) -> Result<(), Self::Error>;
    fn unsafe_regenerate(
        all: impl IntoIterator<Item = AccountId>,
        score_of: Box<dyn Fn(&AccountId) -> Option<Self::Score>>,
    ) -> u32;
    fn unsafe_clear();
    fn try_state() -> Result<(), TryRuntimeError>;
    fn score_update_worst_case(
        _who: &AccountId,
        _is_increase: bool,
    ) -> Self::Score;

    // Provided methods
    fn range() -> (Self::Score, Self::Score) { ... }
    fn on_increase(
        id: &AccountId,
        additional: Self::Score,
    ) -> Result<(), Self::Error> { ... }
    fn on_decrease(
        id: &AccountId,
        decreased: Self::Score,
    ) -> Result<(), Self::Error> { ... }
}

A utility trait for something to implement ElectionDataProvider in a sensible way.

This is generic over AccountId and it can represent a validator, a nominator, or any other entity.

The scores (see Self::Score) are ascending, the higher, the better.

Something that implements this trait will do a best-effort sort over ids, and thus can be used on the implementing side of ElectionDataProvider.

Required Associated Types

type Error: Debug

The list’s error type.

type Score: Bounded + Saturating + Zero + Default

The type used by the list to compare nodes for ordering.

Required Methods

fn iter() -> Box<dyn Iterator<Item = AccountId>>

An iterator over the list, which can have take called on it.

fn lock()

Lock the list.

This will prevent subsequent calls to

• Self::on_insert
• Self::on_update
• Self::on_decrease
• Self::on_increase
• Self::on_remove

fn unlock()

Unlock the list. This will nullify the effects of Self::lock.

fn iter_from( start: &AccountId, ) -> Result<Box<dyn Iterator<Item = AccountId>>, Self::Error>

Returns an iterator over the list, starting right after from the given voter.

May return an error if start is invalid.

fn count() -> u32

The current count of ids in the list.

fn contains(id: &AccountId) -> bool

Return true if the list already contains id.

fn on_insert(id: AccountId, score: Self::Score) -> Result<(), Self::Error>

Hook for inserting a new id.

Implementation should return an error if duplicate item is being inserted.

fn on_update(id: &AccountId, score: Self::Score) -> Result<(), Self::Error>

Hook for updating a single id.

The new score is given.

Returns Ok(()) iff it successfully updates an item, an Err(_) otherwise.

fn get_score(id: &AccountId) -> Result<Self::Score, Self::Error>

Get the score of id.

fn on_remove(id: &AccountId) -> Result<(), Self::Error>

Hook for removing am id from the list.

Returns Ok(()) iff it successfully removes an item, an Err(_) otherwise.

fn unsafe_regenerate( all: impl IntoIterator<Item = AccountId>, score_of: Box<dyn Fn(&AccountId) -> Option<Self::Score>>, ) -> u32

Regenerate this list from scratch. Returns the count of items inserted.

This should typically only be used at a runtime upgrade.

WARNING

This function should be called with care, regenerate will remove the current list write the new list, which can lead to too many storage accesses, exhausting the block weight.

fn unsafe_clear()

Remove all items from the list.

WARNING

This function should never be called in production settings because it can lead to an unbounded amount of storage accesses.

fn try_state() -> Result<(), TryRuntimeError>

Check internal state of the list. Only meant for debugging.

fn score_update_worst_case(_who: &AccountId, _is_increase: bool) -> Self::Score

If who changes by the returned amount they are guaranteed to have a worst case change in their list position.

Provided Methods

fn range() -> (Self::Score, Self::Score)

A typical range for this list.

By default, this would be implemented as Bounded impl of Self::Score.

If this is implemented by a bags-list instance, it will be the smallest and largest bags.

This is useful to help another pallet that consumes this trait generate an even distribution of nodes for testing/genesis.

fn on_increase( id: &AccountId, additional: Self::Score, ) -> Result<(), Self::Error>

Same as on_update, but incorporate some increased score.

fn on_decrease( id: &AccountId, decreased: Self::Score, ) -> Result<(), Self::Error>

Same as on_update, but incorporate some decreased score.

If the new score of the item is Zero, it is removed.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<T: Config<I>, I: 'static> SortedListProvider<<T as Config>::AccountId> for Pallet<T, I>

impl<T: Config> SortedListProvider<<T as Config>::AccountId> for UseNominatorsAndValidatorsMap<T>

impl<T: Config> SortedListProvider<<T as Config>::AccountId> for UseValidatorsMap<T>

impl<T: Config> SortedListProvider<<T as Config>::AccountId> for UseNominatorsAndValidatorsMap<T>

impl<T: Config> SortedListProvider<<T as Config>::AccountId> for UseValidatorsMap<T>