view release on metacpan or  search on metacpan

lib/Acme/Selection/RarestFirst.pod  view on Meta::CPAN

=pod

=encoding utf-8

=head1 NAME

Acme::Selection::RarestFirst - Rarest-First Selection Algorithm

=head1 SYNOPSIS

    use Acme::Selection::RarestFirst;

    my $selector = Acme::Selection::RarestFirst->new( size => 100 );

    # Update availability based on what peers have
    $selector->update( $peer_bitfield, 1 ); # peer joined
    $selector->update( $peer_bitfield, -1); # peer left

    # Pick the next best item to request
    my $idx = $selector->pick( $my_bitfield );

=head1 DESCRIPTION

C<Acme::Selection::RarestFirst> implements the classic "rarest-first" algorithm used in distributed systems to ensure
high data availability. It prioritizes items that have the lowest count in the global set (the "swarm").

=head1 METHODS

=head2 C<update( $bitfield, $delta )>

Increments or decrements the availability count for every item marked in the provided bitfield (which must support a
C<get( $index )> method).

=head2 C<pick( $my_bitfield, [$priorities] )>

Finds the rarest item that is B<not> present in C<$my_bitfield>.

C<$priorities> is an optional arrayref of weights. Items with priority less than or equal to 0 are skipped. Higher
weights are picked before lower weights, even if they aren't the rarest.

=head2 C<get_availability( $index )>

Returns the current availability count for a specific item.

=head1 AUTHOR

Sanko Robinson E<lt>sanko@cpan.orgE<gt>

=head1 COPYRIGHT

Copyright (C) 2026 by Sanko Robinson.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

=cut