Devel::Events(3)

NAME
Devel::Events - Extensible instrumentation framework.

SYNOPSIS
        use Devel::Events::Generator::Foo;
        use Devel::Events::Handler::Bar;
        use Devel::Events::Filter::Blort;

        my $h = Devel::Events::Generator->new(
                handler => Devel::Event::Filter->new(
                        handler => Devel::Events::Handler::Bar->new(),
                ),
        );

DESCRIPTION
Devel::Events is an event generation, filtering and analaysis framework for instrumenting and auditing perl code.

The design's purpose is to decouple the mechanics of code instrumentation from the analysis, making it easier to write debugging/profiling tools.

Devel::Events::Generator object fire events, which can be mangled by Devel::Event::Filter objects. Eventually any number of Devel::Event::Handler objects can receive a given event, and perform analysis based on it.

For example Devel::Event::Handler::ObjectTracker can be used to detect leaks.

COMPONENT OVERVIEW
There are two main types of components - generators and handlers.

Filters are special types of handlers that always delegate to another handler.

The multiplex handler may be used to delegate to any number of handlers, and can be the handler for several generators.

Using these basic components complex chains of handlers can be built to properly analyze the events you are interested in.

  Generators

Devel::Events::Generator::Objects
    Generate "object_bless" and "object_destroy" events by overriding "CORE::GLOBAL::bless" and tracking every object using Variable::Magic.

Devel::Events::Generator::SubTrace
    Uses the perl debugger hook to generate "enter_sub" and "leave_sub" events.

Devel::Events::Generator::LineTrace
    Fires an "executing_line" event for every line using the perl debugger hook.

Devel::Events::Generator::Require
    Fires events for "require" and c<use> calls.

  Handlers

Devel::Events::Handler::Multiplex
    Repeat events to multiple handlers.

Devel::Events::Handler::Callback
    Make a handler object out of a callback.

Devel::Events::Handler::Log::Memory
    Log all events to an array.

    Provides filtering and slicing methods to ease analysis.

Devel::Events::Handler::ObjectTracker
    Handles "object_bless" and "object_destroy" events (as generated by Devel::Events::Generator::Objects) to track the lifetime of objects. When objects lifetimes extend beyond the scope they're supposed to be destroyed in leaks can be detected.}

  Filters

Devel::Events::Filter::Stamp
    Add various stamp data (time, process ID, thread ID if threads are loaded) to events.

Devel::Events::Filter::Stringify
    Stringify (by default using "StrVal" in overload, to avoid side effects) all event data to avoid leaking.

Devel::Events::Filter::Size
    Add size reports to events using Devel::Size

Devel::Events::Filter::RemoveFields
    Remove certain fields from events.

Devel::Events::Filter::Warn
    Runs "warn "@event"" before delegating to the sub handler. Useful for debugging handler chains.

EVENT STRUCTURE
All events are passed as lists.

The default components will generate lists containing a single string which is the event name, and then a list of key/value pairs.

AUTHOR
Yuval Kogman <nothingmuch@woobling.org>

COPYRIGHT & LICENSE
        Copyright (c) 2007 Yuval Kogman. All rights reserved
        This program is free software; you can redistribute it and/or modify it
        under the terms of the MIT license or the same terms as Perl itself.

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 62:
    '=item' outside of any '=over'

Around line 79:
    You forgot a '=back' before '=head2'

Around line 81:
    '=item' outside of any '=over'