view release on metacpan or  search on metacpan

Bucketizer.pm  view on Meta::CPAN

Return a list of buckets. The list contains elements of type 
C<Algorithm::Bucketizer::Bucket>, which understand the following methods:

=over 4

=item *

    my @items = $bucket->items();

Returns a list of names of items in the bucket. 
Returns an empty list if the bucket is empty.

=item *

    my $level = $bucket->level();

Return how full the bucket is. That's the size of all items 
in the bucket combined.

=item *

    my $bucket_index = $bucket->idx();

Return the bucket's index. The first bucket has index 0.

=item *

    my $serial_number = $bucket->serial();

Return the bucket serial number. That's the bucket index plus 1.

=back

=item *

    $b->add_bucket(
        maxsize => $maxsize
    );

Adds a new bucket to the end of the bucket brigade. This method is useful
for building brigades with buckets of various sizes.

=item *

    $b->current_bucket_idx( $idx );

Set/retrieve the index of the bucket that the C<simple> algorithm will
use first in order to try to insert the next item.

=item *

    $b->optimize(
        algorithm  => $algorithm,
        maxtime    => $seconds,
        maxrounds  => $number_of_rounds 
       );

Optimize bucket distribution. Currently C<"random"> and C<"brute_force">
are implemented. Both can be (C<"random"> I<must> be) terminated
by either the maximum number of seconds (C<maxtime>) or 
iterations (C<maxrounds>).

=back

=head1 EXAMPLE

We've got buckets which hold a weight of 100 each, 
and we've got 10 items weighing 30, 31, 32, ... 39. Distribute 
them into buckets.

    use Algorithm::Bucketizer;

    my $b = Algorithm::Bucketizer->new( bucketsize => 100 );
    for my $i (1..10) {
        $b->add_item($i, 30+$i);
    }

    for my $bucket ($b->buckets()) {
        for my $item ($bucket->items()) {
            print "Bucket ", $bucket->serial(), ": Item $item\n";
        }
        print "\n";
    }

Output:

    Bucket 1: Item 1
    Bucket 1: Item 2
    Bucket 1: Item 3

    Bucket 2: Item 4
    Bucket 2: Item 5

    Bucket 3: Item 6
    Bucket 3: Item 7

    Bucket 4: Item 8
    Bucket 4: Item 9

    Bucket 5: Item 10

=head1 REQUIRES

Algorithm::Permute 0.04 if you want to use the "brute_force" method.

=head1 SCRIPTS

This distribution comes with a script I<bucketize> which puts files
into directory buckets with limited size. Run C<perldoc bucketize>
for details.

=head1 AUTHOR

Mike Schilli, E<lt>m@perlmeister.comE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2002-2007 by Mike Schilli

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.