lib/DBIx/Class/ResultSourceHandle.pm

   1 package DBIx::Class::ResultSourceHandle;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/DBIx::Class/;
   7
   8 use DBIx::Class::Exception;
   9 use Try::Tiny;
  10
  11 use namespace::clean;
  12
  13 use overload
  14     q/""/ => sub { __PACKAGE__ . ":" . shift->source_moniker; },
  15     fallback => 1;
  16
  17 __PACKAGE__->mk_group_accessors('simple' => qw/schema source_moniker _detached_source/);
  18
  19 # Schema to use when thawing.
  20 our $thaw_schema;
  21
  22 =head1 NAME
  23
  24 DBIx::Class::ResultSourceHandle - Serializable pointers to ResultSource instances
  25
  26 =head1 DESCRIPTION
  27
  28 Currently instances of this class are used to allow proper serialization of
  29 L<ResultSources|DBIx::Class::ResultSource> (which may contain unserializable
  30 elements like C<CODE> references).
  31
  32 Originally this module was used to remove the fixed link between
  33 L<Rows|DBIx::Class::Row>/L<ResultSets|DBIx::Class::ResultSet> and the actual
  34 L<result source objects|DBIx::Class::ResultSource> in order to obviate the need
  35 of keeping a L<schema instance|DBIx::Class::Schema> constantly in scope, while
  36 at the same time avoiding leaks due to circular dependencies. This is however
  37 no longer needed after introduction of a proper mutual-assured-destruction
  38 contract between a C<Schema> instance and its C<ResultSource> registrants.
  39
  40 =head1 METHODS
  41
  42 =head2 new
  43
  44 =cut
  45
  46 sub new {
  47   my ($class, $args) = @_;
  48   my $self = bless $args, ref $class || $class;
  49
  50   unless( ($self->{schema} || $self->{_detached_source}) && $self->{source_moniker} ) {
  51     my $err = 'Expecting a schema instance and a source moniker';
  52     $self->{schema}
  53       ? $self->{schema}->throw_exception($err)
  54       : DBIx::Class::Exception->throw($err)
  55   }
  56
  57   $self;
  58 }
  59
  60 =head2 resolve
  61
  62 Resolve the moniker into the actual ResultSource object
  63
  64 =cut
  65
  66 sub resolve {
  67   return $_[0]->{schema}->source($_[0]->source_moniker) if $_[0]->{schema};
  68
  69   $_[0]->_detached_source || DBIx::Class::Exception->throw( sprintf (
  70     # vague error message as this is never supposed to happen
  71     "Unable to resolve moniker '%s' - please contact the dev team at %s",
  72     $_[0]->source_moniker,
  73     'http://search.cpan.org/dist/DBIx-Class/lib/DBIx/Class.pm#GETTING_HELP/SUPPORT',
  74   ), 'full_stacktrace');
  75 }
  76
  77 =head2 STORABLE_freeze
  78
  79 Freezes a handle.
  80
  81 =cut
  82
  83 sub STORABLE_freeze {
  84   my ($self, $cloning) = @_;
  85
  86   my $to_serialize = { %$self };
  87
  88   delete $to_serialize->{schema};
  89   delete $to_serialize->{_detached_source};
  90   $to_serialize->{_frozen_from_class} = $self->{schema}
  91     ? $self->{schema}->class($self->source_moniker)
  92     : $self->{_detached_source}->result_class
  93   ;
  94
  95   Storable::nfreeze($to_serialize);
  96 }
  97
  98 =head2 STORABLE_thaw
  99
 100 Thaws frozen handle. Resets the internal schema reference to the package
 101 variable C<$thaw_schema>. The recommended way of setting this is to use
 102 C<< $schema->thaw($ice) >> which handles this for you.
 103
 104 =cut
 105
 106 sub STORABLE_thaw {
 107   my ($self, $cloning, $ice) = @_;
 108   %$self = %{ Storable::thaw($ice) };
 109
 110   my $from_class = delete $self->{_frozen_from_class};
 111
 112   if( $thaw_schema ) {
 113     $self->schema( $thaw_schema );
 114   }
 115   elsif( my $rs = $from_class->result_source_instance ) {
 116     # in the off-chance we are using CDBI-compat and have leaked $schema already
 117     if( my $s = try { $rs->schema } ) {
 118       $self->schema( $s );
 119     }
 120     else {
 121       $rs->source_name( $self->source_moniker );
 122       $rs->{_detached_thaw} = 1;
 123       $self->_detached_source( $rs );
 124     }
 125   }
 126   else {
 127     DBIx::Class::Exception->throw(
 128       "Thaw failed - original result class '$from_class' does not exist on this system"
 129     );
 130   }
 131 }
 132
 133 =head1 AUTHOR
 134
 135 Ash Berlin C<< <ash@cpan.org> >>
 136
 137 =cut
 138
 139 1;