/ 
package-watchdog-0.07
++
/ Package::Watchdog::Sub

NAME

Package::Watchdog::Sub - Base object for managing overriden subroutines.

DESCRIPTION

Only once instance of a class based on this one can exist per package and sub. Each instance manages exactly one sub. When the instance is created it overrides the subroutine with a new one. The instance will expire when the original sub is restored.

ACCESSORS

The following accessors methods are automatically generated using Package::Watchdog::Util::build_accessors().

package()

Name of the package the sub is in.

sub()

Name of the sub being managed.

trackers()

List of the Package::Watchdog::Tracker objects that are tracking the sub.

METHODS

_instance( $class, $package, $sub )

Get/Set the current instance of $class built for $package::$sub. FOR INTERNAL USE ONLY!

$sub_ref = new_sub()

Must be overriden by a subclass. Should return a replacement sub for the sub being managed.

$sub_ref = _new_sub()

FOR INTERNAL USE ONLY

Wraps the sub from new_sub() in additional logic to ensure the original sub is restored after an exception.

init( $self, @params )

Called by new() after object construction. Passed $self and extra parameters from new(). Should be overriden by a subclass for extar construction work.

$obj = $class->new( $package, $sub, $tracker, @params )

Constructs a new instance, or returns the existing instance of $class managing $package::$sub. In the case of an existing instance the tracker is appended to the list of trackers. @params is passed to init().

init() is called both for new instances and existing.

do_override()

INTERNAL USE ONLY!

Replaces the managed sub with _new_sub(). Will refuse to run if the instance has expired. Automatically called by new(), you should NEVER need to runthis yourself.

restore()

Restore the original subroutine and expire this instance.

add_tracker( $tracker )

Add a tracker to the list of trackers.

remove_tracker( $tracker )

Remove a tracker from the list. Must pass in a reference to the tracker that should be removed.

Instance will expire and restore original sub when all trackers have been removed.

You should never need to call this yourself, it is usually called by a tracker itself.

AUTHORS

Chad Granum chad@opensourcery.com

COPYRIGHT

Copyright (C) 2009 OpenSourcery, LLC

Package-Watchdog is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Package-Watchdog is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Package-Watchdog is packaged with a copy of the GNU General Public License. Please see docs/COPYING in this distribution.