lib/DBM/Deep/Iterator/BucketList.pm

   1 package DBM::Deep::Iterator::BucketList;
   2
   3 use 5.006_000;
   4
   5 use strict;
   6 use warnings FATAL => 'all';
   7
   8 =head1 NAME
   9
  10 DBM::Deep::Iterator::BucketList
  11
  12 =head1 PURPOSE
  13
  14 This is an internal-use-only object for L<DBM::Deep/>. It acts as the mediator
  15 between the L<DBM::Deep::Iterator/> object and a L<DBM::Deep::Engine::Sector::BucketList/>
  16 sector.
  17
  18 =head1 OVERVIEW
  19
  20 This object, despite the implied class hiearchy, does B<NOT> inherit from
  21 L<DBM::Deep::Iterator/>. Instead, it delegates to it, essentially acting as a
  22 facade over it. L<DBM::Deep::Iterator/get_next_key> will instantiate one of
  23 these objects as needed to handle an BucketList sector.
  24
  25 =head1 METHODS
  26
  27 =head2 new(\%params)
  28
  29 The constructor takes a hashref of params and blesses it into the invoking class. The
  30 hashref is assumed to have the following elements:
  31
  32 =over 4
  33
  34 =item * iterator (of type L<DBM::Deep::Iterator/>
  35
  36 =item * sector (of type L<DBM::Deep::Engine::Sector::BucketList/>
  37
  38 =back
  39
  40 =cut
  41
  42 sub new {
  43     my $self = bless $_[1] => $_[0];
  44     $self->{curr_index} = 0;
  45     return $self;
  46 }
  47
  48 =head2 at_end()
  49
  50 This takes no arguments.
  51
  52 This returns true/false indicating whether this sector has any more elements that can be
  53 iterated over.
  54
  55 =cut
  56
  57 sub at_end {
  58     my $self = shift;
  59     return $self->{curr_index} >= $self->{iterator}{engine}->max_buckets;
  60 }
  61
  62 =head2 get_next_iterator()
  63
  64 This takes no arguments.
  65
  66 This returns the next key pointed to by this bucketlist. This value is suitable for
  67 returning by FIRSTKEY or NEXTKEY().
  68
  69 If the bucketlist is exhausted, it returns nothing.
  70
  71 =cut
  72
  73 sub get_next_key {
  74     my $self = shift;
  75
  76     return if $self->at_end;
  77
  78     my $idx = $self->{curr_index}++;
  79
  80     my $data_loc = $self->{sector}->get_data_location_for({
  81         allow_head => 1,
  82         idx        => $idx,
  83     }) or return;
  84
  85     #XXX Do we want to add corruption checks here?
  86     return $self->{sector}->get_key_for( $idx )->data;
  87 }
  88
  89 1;
  90 __END__