File Coverage

blib/lib/Devel/Events.pm
Criterion Covered Total %
statement 6 6 100.0
branch n/a
condition n/a
subroutine 2 2 100.0
pod n/a
total 8 8 100.0


line stmt bran cond sub pod time code
1             #!/usr/bin/perl
2              
3             package Devel::Events;
4              
5 1     1   26582 use strict;
  1         3  
  1         33  
6 1     1   5 use warnings;
  1         2  
  1         47  
7              
8             our $VERSION = "0.08";
9              
10             __PACKAGE__;
11              
12             __END__
13              
14             =pod
15              
16             =head1 NAME
17              
18             Devel::Events - Extensible instrumentation framework.
19              
20             =head1 SYNOPSIS
21              
22             use Devel::Events::Generator::Foo;
23             use Devel::Events::Handler::Bar;
24             use Devel::Events::Filter::Blort;
25              
26             my $h = Devel::Events::Generator->new(
27             handler => Devel::Event::Filter->new(
28             handler => Devel::Events::Handler::Bar->new(),
29             ),
30             );
31              
32             =head1 DESCRIPTION
33              
34             L<Devel::Events> is an event generation, filtering and analaysis framework for
35             instrumenting and auditing perl code.
36              
37             The design's purpose is to decouple the mechanics of code instrumentation from
38             the analysis, making it easier to write debugging/profiling tools.
39              
40             L<Devel::Events::Generator> object fire events, which can be mangled by
41             L<Devel::Event::Filter> objects. Eventually any number of
42             L<Devel::Event::Handler> objects can receive a given event, and perform
43             analysis based on it.
44              
45             For example L<Devel::Event::Handler::ObjectTracker> can be used to detect
46             leaks.
47              
48             =head1 COMPONENT OVERVIEW
49              
50             There are two main types of components - generators and handlers.
51              
52             Filters are special types of handlers that always delegate to another handler.
53              
54             The multiplex handler may be used to delegate to any number of handlers, and
55             can be the handler for several generators.
56              
57             Using these basic components complex chains of handlers can be built to
58             properly analyze the events you are interested in.
59              
60             =head2 Generators
61              
62             =item L<Devel::Events::Generator::Objects>
63              
64             Generate C<object_bless> and C<object_destroy> events by overriding
65             C<CORE::GLOBAL::bless> and tracking every object using L<Variable::Magic>.
66              
67             =item L<Devel::Events::Generator::SubTrace>
68              
69             Uses the perl debugger hook to generate C<enter_sub> and C<leave_sub> events.
70              
71             =item L<Devel::Events::Generator::LineTrace>
72              
73             Fires an C<executing_line> event for every line using the perl debugger hook.
74              
75             =item L<Devel::Events::Generator::Require>
76              
77             Fires events for C<require> and c<use> calls.
78              
79             =head2 Handlers
80              
81             =item L<Devel::Events::Handler::Multiplex>
82              
83             Repeat events to multiple handlers.
84              
85             =item L<Devel::Events::Handler::Callback>
86              
87             Make a handler object out of a callback.
88              
89             =item L<Devel::Events::Handler::Log::Memory>
90              
91             Log all events to an array.
92              
93             Provides filtering and slicing methods to ease analysis.
94              
95             =item L<Devel::Events::Handler::ObjectTracker>
96              
97             Handles C<object_bless> and C<object_destroy> events (as generated by
98             L<Devel::Events::Generator::Objects>) to track the lifetime of objects. When
99             objects lifetimes extend beyond the scope they're supposed to be destroyed in
100             leaks can be detected.}
101              
102             =back
103              
104             =head2 Filters
105              
106             =over 4
107              
108             =item L<Devel::Events::Filter::Stamp>
109              
110             Add various stamp data (time, process ID, thread ID if threads are loaded) to
111             events.
112              
113             =item L<Devel::Events::Filter::Stringify>
114              
115             Stringify (by default using L<overload/StrVal>, to avoid side effects) all
116             event data to avoid leaking.
117              
118             =item L<Devel::Events::Filter::Size>
119              
120             Add size reports to events using L<Devel::Size>
121              
122             =item L<Devel::Events::Filter::RemoveFields>
123              
124             Remove certain fields from events.
125              
126              
127             =item L<Devel::Events::Filter::Warn>
128              
129             Runs C<warn "@event"> before delegating to the sub handler. Useful for
130             debugging handler chains.
131              
132             =back
133              
134             =head1 EVENT STRUCTURE
135              
136             All events are passed as lists.
137              
138             The default components will generate lists containing a single string which is
139             the event name, and then a list of key/value pairs.
140              
141             =head1 AUTHOR
142              
143             Yuval Kogman <nothingmuch@woobling.org>
144              
145             =head1 COPYRIGHT & LICENSE
146              
147             Copyright (c) 2007 Yuval Kogman. All rights reserved
148             This program is free software; you can redistribute it and/or modify it
149             under the terms of the MIT license or the same terms as Perl itself.
150              
151             =cut
152              
153