NAME

SYNOPSIS

  use Algorithm::Bucketizer;

      # Create a bucketizer
  my $bucketizer = Algorithm::Bucketizer->new(bucketsize => $size);

      # Add items to it
  $bucketizer->add_item($item, $size);

      # Optimize distribution
  $bucketizer->optimize(maxrounds => 100);

      # When done adding, get the buckets
      # (they're of type Algorithm::Bucketizer::Bucket)
  my @buckets = $bucketizer->buckets();

      # Access bucket content by using
      # Algorithm::Bucketizer::Bucket methods
  my @items  = $bucket->items();
  my $serial = $bucket->serial();

DESCRIPTION

"Algorithm::Bucketizer" distributes items of a defined size into a number of dynamically created buckets, each of them capable of holding items of a defined total size.

By calling the "$bucketizer->add_item()" method with the item (can be a scalar or an object reference) and its size as parameters, you're adding items to the system. The bucketizer will determine if the item fits into one of the existing buckets and put it in there if possible. If none of the existing buckets has enough space left to hold the new item (or if no buckets exist yet for that matter), the bucketizer will create a new bucket and put the item in there.

After adding all items to the system, the bucketizer lets you iterate over all buckets with the "$bucketizer->items()" method and determine what's in each of them.

    my $dumb = Algorithm::Bucketizer->new( algorithm => "simple" );

    my $smart = Algorithm::Bucketizer->new( algorithm => "retry" );

    $b->prefill_bucket($bucket_idx, $item, $itemsize);

        # Try randomly to improve distribution, 
        # timing out after 100 rounds
    $b->optimize(algorithm => "random", maxrounds => 100);

        # Try randomly to improve distribution, 
        # timing out after 60 secs
    $b->optimize(algorithm => "random", maxtime => 60);

        # Try to improve distribution by brute_force trying
        # all possible combinations (watch out: can take forever)
    $b->optimize(algorithm => "brute_force",
                 maxtime => ..., 
                 maxrounds => ...,
                );

FUNCTIONS

•     my $b = Algorithm::Bucketizer->new(
          bucketsize => $size, 
          algorithm  => $algorithm 
         );
      

  Creates a new "Algorithm::Bucketizer" object and returns a reference to it.

  The "bucketsize" name-value pair is somewhat mandatory, because you want to set the size of your buckets, otherwise they will default to 100, which isn't what you want in most cases.

  "algorithm" can be left out, it defaults to "simple". If you want retry behaviour, specify "retry" (see "Algorithms").

  Another optional parameter, "add_buckets" specifies if the bucketizer is allowed to add new buckets to the end of the brigade as it sees fit. It defaults to 1. If set to 0, the bucketizer will operate with a limited number of buckets, usually defined by "add_bucket" calls.

•     $b->add_item($item_name, $item_size);
      

  Adds an item with the specified name and size to the next available bucket, according to the chosen algorithm. If you want to place an item into a specific bucket (e.g. in order to prefill buckets), use "prefill_bucket()" instead, which is described below.

  Returns the Algorithm::Bucketizer::Bucket object of the lucky bucket on sucess and "undef" if something goes badly wrong (e.g. the bucket size is smaller than the item, i.e. there's no way it's ever going to fit in any bucket).

•     my @buckets = $b->buckets();
      

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

•     $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.

•     $b->current_bucket_idx( $idx );
      

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

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

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

EXAMPLE

    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

REQUIRES

SCRIPTS

AUTHOR

COPYRIGHT AND LICENSE

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