[Summary view] [Print] [Text view]

   1  =head1 NAME
   2  X<object> X<OOP>
   3  
   4  perlobj - Perl objects
   5  
   6  =head1 DESCRIPTION
   7  
   8  First you need to understand what references are in Perl.
   9  See L<perlref> for that.  Second, if you still find the following
  10  reference work too complicated, a tutorial on object-oriented programming
  11  in Perl can be found in L<perltoot> and L<perltooc>.
  12  
  13  If you're still with us, then
  14  here are three very simple definitions that you should find reassuring.
  15  
  16  =over 4
  17  
  18  =item 1.
  19  
  20  An object is simply a reference that happens to know which class it
  21  belongs to.
  22  
  23  =item 2.
  24  
  25  A class is simply a package that happens to provide methods to deal
  26  with object references.
  27  
  28  =item 3.
  29  
  30  A method is simply a subroutine that expects an object reference (or
  31  a package name, for class methods) as the first argument.
  32  
  33  =back
  34  
  35  We'll cover these points now in more depth.
  36  
  37  =head2 An Object is Simply a Reference
  38  X<object> X<bless> X<constructor> X<new>
  39  
  40  Unlike say C++, Perl doesn't provide any special syntax for
  41  constructors.  A constructor is merely a subroutine that returns a
  42  reference to something "blessed" into a class, generally the
  43  class that the subroutine is defined in.  Here is a typical
  44  constructor:
  45  
  46      package Critter;
  47      sub new { bless {} }
  48  
  49  That word C<new> isn't special.  You could have written
  50  a construct this way, too:
  51  
  52      package Critter;
  53      sub spawn { bless {} }
  54  
  55  This might even be preferable, because the C++ programmers won't
  56  be tricked into thinking that C<new> works in Perl as it does in C++.
  57  It doesn't.  We recommend that you name your constructors whatever
  58  makes sense in the context of the problem you're solving.  For example,
  59  constructors in the Tk extension to Perl are named after the widgets
  60  they create.
  61  
  62  One thing that's different about Perl constructors compared with those in
  63  C++ is that in Perl, they have to allocate their own memory.  (The other
  64  things is that they don't automatically call overridden base-class
  65  constructors.)  The C<{}> allocates an anonymous hash containing no
  66  key/value pairs, and returns it  The bless() takes that reference and
  67  tells the object it references that it's now a Critter, and returns
  68  the reference.  This is for convenience, because the referenced object
  69  itself knows that it has been blessed, and the reference to it could
  70  have been returned directly, like this:
  71  
  72      sub new {
  73      my $self = {};
  74      bless $self;
  75      return $self;
  76      }
  77  
  78  You often see such a thing in more complicated constructors
  79  that wish to call methods in the class as part of the construction:
  80  
  81      sub new {
  82      my $self = {};
  83      bless $self;
  84      $self->initialize();
  85      return $self;
  86      }
  87  
  88  If you care about inheritance (and you should; see
  89  L<perlmodlib/"Modules: Creation, Use, and Abuse">),
  90  then you want to use the two-arg form of bless
  91  so that your constructors may be inherited:
  92  
  93      sub new {
  94      my $class = shift;
  95      my $self = {};
  96      bless $self, $class;
  97      $self->initialize();
  98      return $self;
  99      }
 100  
 101  Or if you expect people to call not just C<< CLASS->new() >> but also
 102  C<< $obj->new() >>, then use something like the following.  (Note that using
 103  this to call new() on an instance does not automatically perform any
 104  copying.  If you want a shallow or deep copy of an object, you'll have to
 105  specifically allow for that.)  The initialize() method used will be of
 106  whatever $class we blessed the object into:
 107  
 108      sub new {
 109      my $this = shift;
 110      my $class = ref($this) || $this;
 111      my $self = {};
 112      bless $self, $class;
 113      $self->initialize();
 114      return $self;
 115      }
 116  
 117  Within the class package, the methods will typically deal with the
 118  reference as an ordinary reference.  Outside the class package,
 119  the reference is generally treated as an opaque value that may
 120  be accessed only through the class's methods.
 121  
 122  Although a constructor can in theory re-bless a referenced object
 123  currently belonging to another class, this is almost certainly going
 124  to get you into trouble.  The new class is responsible for all
 125  cleanup later.  The previous blessing is forgotten, as an object
 126  may belong to only one class at a time.  (Although of course it's
 127  free to inherit methods from many classes.)  If you find yourself
 128  having to do this, the parent class is probably misbehaving, though.
 129  
 130  A clarification:  Perl objects are blessed.  References are not.  Objects
 131  know which package they belong to.  References do not.  The bless()
 132  function uses the reference to find the object.  Consider
 133  the following example:
 134  
 135      $a = {};
 136      $b = $a;
 137      bless $a, BLAH;
 138      print "\$b is a ", ref($b), "\n";
 139  
 140  This reports $b as being a BLAH, so obviously bless()
 141  operated on the object and not on the reference.
 142  
 143  =head2 A Class is Simply a Package
 144  X<class> X<package> X<@ISA> X<inheritance>
 145  
 146  Unlike say C++, Perl doesn't provide any special syntax for class
 147  definitions.  You use a package as a class by putting method
 148  definitions into the class.
 149  
 150  There is a special array within each package called @ISA, which says
 151  where else to look for a method if you can't find it in the current
 152  package.  This is how Perl implements inheritance.  Each element of the
 153  @ISA array is just the name of another package that happens to be a
 154  class package.  The classes are searched for missing methods in
 155  depth-first, left-to-right order by default (see L<mro> for alternative
 156  search order and other in-depth information).  The classes accessible
 157  through @ISA are known as base classes of the current class.
 158  
 159  All classes implicitly inherit from class C<UNIVERSAL> as their
 160  last base class.  Several commonly used methods are automatically
 161  supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> for
 162  more details.
 163  X<UNIVERSAL> X<base class> X<class, base>
 164  
 165  If a missing method is found in a base class, it is cached
 166  in the current class for efficiency.  Changing @ISA or defining new
 167  subroutines invalidates the cache and causes Perl to do the lookup again.
 168  
 169  If neither the current class, its named base classes, nor the UNIVERSAL
 170  class contains the requested method, these three places are searched
 171  all over again, this time looking for a method named AUTOLOAD().  If an
 172  AUTOLOAD is found, this method is called on behalf of the missing method,
 173  setting the package global $AUTOLOAD to be the fully qualified name of
 174  the method that was intended to be called.
 175  X<AUTOLOAD>
 176  
 177  If none of that works, Perl finally gives up and complains.
 178  
 179  If you want to stop the AUTOLOAD inheritance say simply
 180  X<AUTOLOAD>
 181  
 182      sub AUTOLOAD;
 183  
 184  and the call will die using the name of the sub being called.
 185  
 186  Perl classes do method inheritance only.  Data inheritance is left up
 187  to the class itself.  By and large, this is not a problem in Perl,
 188  because most classes model the attributes of their object using an
 189  anonymous hash, which serves as its own little namespace to be carved up
 190  by the various classes that might want to do something with the object.
 191  The only problem with this is that you can't sure that you aren't using
 192  a piece of the hash that isn't already used.  A reasonable workaround
 193  is to prepend your fieldname in the hash with the package name.
 194  X<inheritance, method> X<inheritance, data>
 195  
 196      sub bump {
 197      my $self = shift;
 198      $self->{ __PACKAGE__ . ".count"}++;
 199      } 
 200  
 201  =head2 A Method is Simply a Subroutine
 202  X<method>
 203  
 204  Unlike say C++, Perl doesn't provide any special syntax for method
 205  definition.  (It does provide a little syntax for method invocation
 206  though.  More on that later.)  A method expects its first argument
 207  to be the object (reference) or package (string) it is being invoked
 208  on.  There are two ways of calling methods, which we'll call class
 209  methods and instance methods.  
 210  
 211  A class method expects a class name as the first argument.  It
 212  provides functionality for the class as a whole, not for any
 213  individual object belonging to the class.  Constructors are often
 214  class methods, but see L<perltoot> and L<perltooc> for alternatives.
 215  Many class methods simply ignore their first argument, because they
 216  already know what package they're in and don't care what package
 217  they were invoked via.  (These aren't necessarily the same, because
 218  class methods follow the inheritance tree just like ordinary instance
 219  methods.)  Another typical use for class methods is to look up an
 220  object by name:
 221  
 222      sub find {
 223      my ($class, $name) = @_;
 224      $objtable{$name};
 225      }
 226  
 227  An instance method expects an object reference as its first argument.
 228  Typically it shifts the first argument into a "self" or "this" variable,
 229  and then uses that as an ordinary reference.
 230  
 231      sub display {
 232      my $self = shift;
 233      my @keys = @_ ? @_ : sort keys %$self;
 234      foreach $key (@keys) {
 235          print "\t$key => $self->{$key}\n";
 236      }
 237      }
 238  
 239  =head2 Method Invocation
 240  X<invocation> X<method> X<arrow> X<< -> >>
 241  
 242  For various historical and other reasons, Perl offers two equivalent
 243  ways to write a method call.  The simpler and more common way is to use
 244  the arrow notation:
 245  
 246      my $fred = Critter->find("Fred");
 247      $fred->display("Height", "Weight");
 248  
 249  You should already be familiar with the use of the C<< -> >> operator with
 250  references.  In fact, since C<$fred> above is a reference to an object,
 251  you could think of the method call as just another form of
 252  dereferencing.
 253  
 254  Whatever is on the left side of the arrow, whether a reference or a
 255  class name, is passed to the method subroutine as its first argument.
 256  So the above code is mostly equivalent to:
 257  
 258      my $fred = Critter::find("Critter", "Fred");
 259      Critter::display($fred, "Height", "Weight");
 260  
 261  How does Perl know which package the subroutine is in?  By looking at
 262  the left side of the arrow, which must be either a package name or a
 263  reference to an object, i.e. something that has been blessed to a
 264  package.  Either way, that's the package where Perl starts looking.  If
 265  that package has no subroutine with that name, Perl starts looking for
 266  it in any base classes of that package, and so on.
 267  
 268  If you need to, you I<can> force Perl to start looking in some other package:
 269  
 270      my $barney = MyCritter->Critter::find("Barney");
 271      $barney->Critter::display("Height", "Weight");
 272  
 273  Here C<MyCritter> is presumably a subclass of C<Critter> that defines
 274  its own versions of find() and display().  We haven't specified what
 275  those methods do, but that doesn't matter above since we've forced Perl
 276  to start looking for the subroutines in C<Critter>.
 277  
 278  As a special case of the above, you may use the C<SUPER> pseudo-class to
 279  tell Perl to start looking for the method in the packages named in the
 280  current class's C<@ISA> list.  
 281  X<SUPER>
 282  
 283      package MyCritter;
 284      use base 'Critter';    # sets @MyCritter::ISA = ('Critter');
 285  
 286      sub display { 
 287          my ($self, @args) = @_;
 288          $self->SUPER::display("Name", @args);
 289      }
 290  
 291  It is important to note that C<SUPER> refers to the superclass(es) of the
 292  I<current package> and not to the superclass(es) of the object. Also, the
 293  C<SUPER> pseudo-class can only currently be used as a modifier to a method
 294  name, but not in any of the other ways that class names are normally used,
 295  eg:
 296  X<SUPER>
 297  
 298      something->SUPER::method(...);    # OK
 299      SUPER::method(...);            # WRONG
 300      SUPER->method(...);            # WRONG
 301  
 302  Instead of a class name or an object reference, you can also use any
 303  expression that returns either of those on the left side of the arrow.
 304  So the following statement is valid:
 305  
 306      Critter->find("Fred")->display("Height", "Weight");
 307  
 308  and so is the following:
 309  
 310      my $fred = (reverse "rettirC")->find(reverse "derF");
 311  
 312  The right side of the arrow typically is the method name, but a simple 
 313  scalar variable containing either the method name or a subroutine 
 314  reference can also be used.
 315  
 316  =head2 Indirect Object Syntax
 317  X<indirect object syntax> X<invocation, indirect> X<indirect>
 318  
 319  The other way to invoke a method is by using the so-called "indirect
 320  object" notation.  This syntax was available in Perl 4 long before
 321  objects were introduced, and is still used with filehandles like this:
 322  
 323     print STDERR "help!!!\n";
 324  
 325  The same syntax can be used to call either object or class methods.
 326  
 327     my $fred = find Critter "Fred";
 328     display $fred "Height", "Weight";
 329  
 330  Notice that there is no comma between the object or class name and the
 331  parameters.  This is how Perl can tell you want an indirect method call
 332  instead of an ordinary subroutine call.
 333  
 334  But what if there are no arguments?  In that case, Perl must guess what
 335  you want.  Even worse, it must make that guess I<at compile time>.
 336  Usually Perl gets it right, but when it doesn't you get a function
 337  call compiled as a method, or vice versa.  This can introduce subtle bugs
 338  that are hard to detect.
 339  
 340  For example, a call to a method C<new> in indirect notation -- as C++
 341  programmers are wont to make -- can be miscompiled into a subroutine
 342  call if there's already a C<new> function in scope.  You'd end up
 343  calling the current package's C<new> as a subroutine, rather than the
 344  desired class's method.  The compiler tries to cheat by remembering
 345  bareword C<require>s, but the grief when it messes up just isn't worth the
 346  years of debugging it will take you to track down such subtle bugs.
 347  
 348  There is another problem with this syntax: the indirect object is
 349  limited to a name, a scalar variable, or a block, because it would have
 350  to do too much lookahead otherwise, just like any other postfix
 351  dereference in the language.  (These are the same quirky rules as are
 352  used for the filehandle slot in functions like C<print> and C<printf>.)
 353  This can lead to horribly confusing precedence problems, as in these
 354  next two lines:
 355  
 356      move $obj->{FIELD};                 # probably wrong!
 357      move $ary[$i];                      # probably wrong!
 358  
 359  Those actually parse as the very surprising:
 360  
 361      $obj->move->{FIELD};                # Well, lookee here
 362      $ary->move([$i]);                   # Didn't expect this one, eh?
 363  
 364  Rather than what you might have expected:
 365  
 366      $obj->{FIELD}->move();              # You should be so lucky.
 367      $ary[$i]->move;                     # Yeah, sure.
 368  
 369  To get the correct behavior with indirect object syntax, you would have
 370  to use a block around the indirect object:
 371  
 372      move {$obj->{FIELD}};
 373      move {$ary[$i]};
 374  
 375  Even then, you still have the same potential problem if there happens to
 376  be a function named C<move> in the current package.  B<The C<< -> >>
 377  notation suffers from neither of these disturbing ambiguities, so we
 378  recommend you use it exclusively.>  However, you may still end up having
 379  to read code using the indirect object notation, so it's important to be
 380  familiar with it.
 381  
 382  =head2 Default UNIVERSAL methods
 383  X<UNIVERSAL>
 384  
 385  The C<UNIVERSAL> package automatically contains the following methods that
 386  are inherited by all other classes:
 387  
 388  =over 4
 389  
 390  =item isa(CLASS)
 391  X<isa>
 392  
 393  C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
 394  
 395  You can also call C<UNIVERSAL::isa> as a subroutine with two arguments.  Of
 396  course, this will do the wrong thing if someone has overridden C<isa> in a
 397  class, so don't do it.
 398  
 399  If you need to determine whether you've received a valid invocant, use the
 400  C<blessed> function from L<Scalar::Util>:
 401  X<invocant> X<blessed>
 402  
 403      if (blessed($ref) && $ref->isa( 'Some::Class')) {
 404          # ...
 405      }
 406  
 407  C<blessed> returns the name of the package the argument has been
 408  blessed into, or C<undef>.
 409  
 410  =item can(METHOD)
 411  X<can>
 412  
 413  C<can> checks to see if its object has a method called C<METHOD>,
 414  if it does then a reference to the sub is returned, if it does not then
 415  I<undef> is returned.
 416  
 417  C<UNIVERSAL::can> can also be called as a subroutine with two arguments.  It'll
 418  always return I<undef> if its first argument isn't an object or a class name.
 419  The same caveats for calling C<UNIVERSAL::isa> directly apply here, too.
 420  
 421  =item VERSION( [NEED] )
 422  X<VERSION>
 423  
 424  C<VERSION> returns the version number of the class (package).  If the
 425  NEED argument is given then it will check that the current version (as
 426  defined by the $VERSION variable in the given package) not less than
 427  NEED; it will die if this is not the case.  This method is normally
 428  called as a class method.  This method is called automatically by the
 429  C<VERSION> form of C<use>.
 430  
 431      use A 1.2 qw(some imported subs);
 432      # implies:
 433      A->VERSION(1.2);
 434  
 435  =back
 436  
 437  B<NOTE:> C<can> directly uses Perl's internal code for method lookup, and
 438  C<isa> uses a very similar method and cache-ing strategy. This may cause
 439  strange effects if the Perl code dynamically changes @ISA in any package.
 440  
 441  You may add other methods to the UNIVERSAL class via Perl or XS code.
 442  You do not need to C<use UNIVERSAL> to make these methods
 443  available to your program (and you should not do so).
 444  
 445  =head2 Destructors
 446  X<destructor> X<DESTROY>
 447  
 448  When the last reference to an object goes away, the object is
 449  automatically destroyed.  (This may even be after you exit, if you've
 450  stored references in global variables.)  If you want to capture control
 451  just before the object is freed, you may define a DESTROY method in
 452  your class.  It will automatically be called at the appropriate moment,
 453  and you can do any extra cleanup you need to do.  Perl passes a reference
 454  to the object under destruction as the first (and only) argument.  Beware
 455  that the reference is a read-only value, and cannot be modified by
 456  manipulating C<$_[0]> within the destructor.  The object itself (i.e.
 457  the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>, 
 458  C<%{$_[0]}> etc.) is not similarly constrained.
 459  
 460  Since DESTROY methods can be called at unpredictable times, it is
 461  important that you localise any global variables that the method may
 462  update.  In particular, localise C<$@> if you use C<eval {}> and
 463  localise C<$?> if you use C<system> or backticks.
 464  
 465  If you arrange to re-bless the reference before the destructor returns,
 466  perl will again call the DESTROY method for the re-blessed object after
 467  the current one returns.  This can be used for clean delegation of
 468  object destruction, or for ensuring that destructors in the base classes
 469  of your choosing get called.  Explicitly calling DESTROY is also possible,
 470  but is usually never needed.
 471  
 472  Do not confuse the previous discussion with how objects I<CONTAINED> in the current
 473  one are destroyed.  Such objects will be freed and destroyed automatically
 474  when the current object is freed, provided no other references to them exist
 475  elsewhere.
 476  
 477  =head2 Summary
 478  
 479  That's about all there is to it.  Now you need just to go off and buy a
 480  book about object-oriented design methodology, and bang your forehead
 481  with it for the next six months or so.
 482  
 483  =head2 Two-Phased Garbage Collection
 484  X<garbage collection> X<GC> X<circular reference>
 485  X<reference, circular> X<DESTROY> X<destructor>
 486  
 487  For most purposes, Perl uses a fast and simple, reference-based
 488  garbage collection system.  That means there's an extra
 489  dereference going on at some level, so if you haven't built
 490  your Perl executable using your C compiler's C<-O> flag, performance
 491  will suffer.  If you I<have> built Perl with C<cc -O>, then this
 492  probably won't matter.
 493  
 494  A more serious concern is that unreachable memory with a non-zero
 495  reference count will not normally get freed.  Therefore, this is a bad
 496  idea:
 497  
 498      {
 499      my $a;
 500      $a = \$a;
 501      }
 502  
 503  Even thought $a I<should> go away, it can't.  When building recursive data
 504  structures, you'll have to break the self-reference yourself explicitly
 505  if you don't care to leak.  For example, here's a self-referential
 506  node such as one might use in a sophisticated tree structure:
 507  
 508      sub new_node {
 509      my $class = shift;
 510      my $node  = {};
 511      $node->{LEFT} = $node->{RIGHT} = $node;
 512      $node->{DATA} = [ @_ ];
 513      return bless $node => $class;
 514      }
 515  
 516  If you create nodes like that, they (currently) won't go away unless you
 517  break their self reference yourself.  (In other words, this is not to be
 518  construed as a feature, and you shouldn't depend on it.)
 519  
 520  Almost.
 521  
 522  When an interpreter thread finally shuts down (usually when your program
 523  exits), then a rather costly but complete mark-and-sweep style of garbage
 524  collection is performed, and everything allocated by that thread gets
 525  destroyed.  This is essential to support Perl as an embedded or a
 526  multithreadable language.  For example, this program demonstrates Perl's
 527  two-phased garbage collection:
 528  
 529      #!/usr/bin/perl
 530      package Subtle;
 531  
 532      sub new {
 533      my $test;
 534      $test = \$test;
 535      warn "CREATING " . \$test;
 536      return bless \$test;
 537      }
 538  
 539      sub DESTROY {
 540      my $self = shift;
 541      warn "DESTROYING $self";
 542      }
 543  
 544      package main;
 545  
 546      warn "starting program";
 547      {
 548      my $a = Subtle->new;
 549      my $b = Subtle->new;
 550      $$a = 0;  # break selfref
 551      warn "leaving block";
 552      }
 553  
 554      warn "just exited block";
 555      warn "time to die...";
 556      exit;
 557  
 558  When run as F</foo/test>, the following output is produced:
 559  
 560      starting program at /foo/test line 18.
 561      CREATING SCALAR(0x8e5b8) at /foo/test line 7.
 562      CREATING SCALAR(0x8e57c) at /foo/test line 7.
 563      leaving block at /foo/test line 23.
 564      DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
 565      just exited block at /foo/test line 26.
 566      time to die... at /foo/test line 27.
 567      DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.
 568  
 569  Notice that "global destruction" bit there?  That's the thread
 570  garbage collector reaching the unreachable.
 571  
 572  Objects are always destructed, even when regular refs aren't.  Objects
 573  are destructed in a separate pass before ordinary refs just to 
 574  prevent object destructors from using refs that have been themselves
 575  destructed.  Plain refs are only garbage-collected if the destruct level
 576  is greater than 0.  You can test the higher levels of global destruction
 577  by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
 578  C<-DDEBUGGING> was enabled during perl build time.
 579  See L<perlhack/PERL_DESTRUCT_LEVEL> for more information.
 580  
 581  A more complete garbage collection strategy will be implemented
 582  at a future date.
 583  
 584  In the meantime, the best solution is to create a non-recursive container
 585  class that holds a pointer to the self-referential data structure.
 586  Define a DESTROY method for the containing object's class that manually
 587  breaks the circularities in the self-referential structure.
 588  
 589  =head1 SEE ALSO
 590  
 591  A kinder, gentler tutorial on object-oriented programming in Perl can
 592  be found in L<perltoot>, L<perlboot> and L<perltooc>.  You should
 593  also check out L<perlbot> for other object tricks, traps, and tips, as
 594  well as L<perlmodlib> for some style guides on constructing both
 595  modules and classes.