NAME

Devel::Events::Generator::Objects - Generate events for blessing and destruction of objects.

SYNOPSIS

        use Devel::Events::Generator::Objects; # must be loaded before any code you want to instrument

        my $g = Devel::Events::Generator::Objects->new(
                handler => $h,
        );

        $g->enable(); # only one Objects generator may be enabled at a time

        $code->(); # objects being created and destroyed cause events to be generated

        $g->disable();

DESCRIPTION

This module overrides CORE::GLOBAL::bless on load. The altered version will delegate back to the original version until an instance of a generator is enabled.

When a generator is enabled (only one Devel::Events::Generator::Objects instance may be enabled at a time. Use Devel::Events::Handler::Multiplex to dup events to multiple listeners), the overridden version of bless will cause an object_bless event to fire, and will also attach magic to the object to keep track of it's destruction using Variable::Magic.

When the object is freed by the interpreter an object_destroy event is fired. Unfortunately by this time perl has already unblessed the object in question, so in order to keep track of the class you must associate it yourself with the reference address.

Devel::Events::Handler::ObjectTracker contains a detailed usage example.

EVENTS

object_bless

When the generator is enabled, this event will fire on every call to bless for all code loaded after this module was loaded.

In the future this event might omit objects created during event handling, but currently it does not.

object

The object that was blessed

old_class

If this is a rebless then this parameter contains the class the object was in just before the bless.

package

file

line

These fields correspond to the location o the call to bless.

object_destroy

For every object created while the generator was enabled, magic to track destruction will be attached. When the object is freed this magic callback will fire this event.

object

This field contains a reference to the object.

NOTE: by the time this callback fires the object is no longer blessed. Be sure to keep track of the class of every refaddr as reported by object_bless in your handler if you need to know the class the object belonged to at destroy time..

METHODS

enable

Make this instance the enabled one (disabling any other instance which is enabled).

This only applies to the object_bless method.

disable

Disable this instance. Will stop generating object_bless events.

bless

The method called by the CORE::GLOBAL::bless hook.

Uses CORE::bless to bless the data, and then calls object_bless.

object_bless

Generates the object_bless event.

Calls rack_object.

object_destroy

Generates the object_destroy event.

Calls untrack_object.

tracker_magic

A class method containing the Variable::Magic specification necessary for track_object to work.

track_object

Attach magic to an object that will call object_destroy when the data is about to be freed.

untrack_object

Currently empty. A subclass with a different implementation of track_object might want to override this.

SEE ALSO

Devel::Object::Leak, Variable::Magic