lib/DBIx/Class/Storage/DBI/Cursor.pm

   1 package DBIx::Class::Storage::DBI::Cursor;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/
   7   Class::Accessor::Grouped
   8   DBIx::Class::Cursor
   9 /;
  10 use mro 'c3';
  11
  12 __PACKAGE__->mk_group_accessors('simple' =>
  13     qw/sth/
  14 );
  15
  16 =head1 NAME
  17
  18 DBIx::Class::Storage::DBI::Cursor - Object representing a query cursor on a
  19 resultset.
  20
  21 =head1 SYNOPSIS
  22
  23   my $cursor = $schema->resultset('CD')->cursor();
  24   my $first_cd = $cursor->next;
  25
  26 =head1 DESCRIPTION
  27
  28 A Cursor represents a query cursor on a L<DBIx::Class::ResultSet> object. It
  29 allows for traversing the result set with L</next>, retrieving all results with
  30 L</all> and resetting the cursor with L</reset>.
  31
  32 Usually, you would use the cursor methods built into L<DBIx::Class::ResultSet>
  33 to traverse it. See L<DBIx::Class::ResultSet/next>,
  34 L<DBIx::Class::ResultSet/reset> and L<DBIx::Class::ResultSet/all> for more
  35 information.
  36
  37 =head1 METHODS
  38
  39 =head2 new
  40
  41 Returns a new L<DBIx::Class::Storage::DBI::Cursor> object.
  42
  43 =cut
  44
  45 sub new {
  46   my ($class, $storage, $args, $attrs) = @_;
  47   $class = ref $class if ref $class;
  48
  49   my $new = {
  50     storage => $storage,
  51     args => $args,
  52     pos => 0,
  53     attrs => $attrs,
  54     _dbh_gen => $storage->{_dbh_gen},
  55   };
  56
  57   return bless ($new, $class);
  58 }
  59
  60 =head2 next
  61
  62 =over 4
  63
  64 =item Arguments: none
  65
  66 =item Return Value: \@row_columns
  67
  68 =back
  69
  70 Advances the cursor to the next row and returns an array of column
  71 values (the result of L<DBI/fetchrow_array> method).
  72
  73 =cut
  74
  75 sub _dbh_next {
  76   my ($storage, $dbh, $self) = @_;
  77
  78   $self->_check_dbh_gen;
  79   if (
  80     $self->{attrs}{software_limit}
  81       && $self->{attrs}{rows}
  82         && $self->{pos} >= $self->{attrs}{rows}
  83   ) {
  84     $self->sth->finish if $self->sth->{Active};
  85     $self->sth(undef);
  86     $self->{done} = 1;
  87   }
  88   return if $self->{done};
  89   unless ($self->sth) {
  90     $self->sth(($storage->_select(@{$self->{args}}))[1]);
  91     if ($self->{attrs}{software_limit}) {
  92       if (my $offset = $self->{attrs}{offset}) {
  93         $self->sth->fetch for 1 .. $offset;
  94       }
  95     }
  96   }
  97   my @row = $self->sth->fetchrow_array;
  98   if (@row) {
  99     $self->{pos}++;
 100   } else {
 101     $self->sth(undef);
 102     $self->{done} = 1;
 103   }
 104   return @row;
 105 }
 106
 107 sub next {
 108   my ($self) = @_;
 109   $self->{storage}->dbh_do($self->can('_dbh_next'), $self);
 110 }
 111
 112 =head2 all
 113
 114 =over 4
 115
 116 =item Arguments: none
 117
 118 =item Return Value: \@row_columns+
 119
 120 =back
 121
 122 Returns a list of arrayrefs of column values for all rows in the
 123 L<DBIx::Class::ResultSet>.
 124
 125 =cut
 126
 127 sub _dbh_all {
 128   my ($storage, $dbh, $self) = @_;
 129
 130   $self->_check_dbh_gen;
 131   $self->sth->finish if $self->sth && $self->sth->{Active};
 132   $self->sth(undef);
 133   my ($rv, $sth) = $storage->_select(@{$self->{args}});
 134   return @{$sth->fetchall_arrayref};
 135 }
 136
 137 sub all {
 138   my ($self) = @_;
 139   if ($self->{attrs}{software_limit}
 140         && ($self->{attrs}{offset} || $self->{attrs}{rows})) {
 141     return $self->next::method;
 142   }
 143
 144   $self->{storage}->dbh_do($self->can('_dbh_all'), $self);
 145 }
 146
 147 =head2 reset
 148
 149 Resets the cursor to the beginning of the L<DBIx::Class::ResultSet>.
 150
 151 =cut
 152
 153 sub reset {
 154   my ($self) = @_;
 155
 156   # No need to care about failures here
 157   eval { $self->sth->finish if $self->sth && $self->sth->{Active} };
 158   $self->_soft_reset;
 159   return undef;
 160 }
 161
 162 sub _soft_reset {
 163   my ($self) = @_;
 164
 165   $self->sth(undef);
 166   delete $self->{done};
 167   $self->{pos} = 0;
 168 }
 169
 170 sub _check_dbh_gen {
 171   my ($self) = @_;
 172
 173   if($self->{_dbh_gen} != $self->{storage}->{_dbh_gen}) {
 174     $self->{_dbh_gen} = $self->{storage}->{_dbh_gen};
 175     $self->_soft_reset;
 176   }
 177 }
 178
 179 sub DESTROY {
 180   my ($self) = @_;
 181
 182   # None of the reasons this would die matter if we're in DESTROY anyways
 183   local $@;
 184   eval { $self->sth->finish if $self->sth && $self->sth->{Active} };
 185 }
 186
 187 1;