The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

SARTAK / MooseX-InstanceTracking-0.06 / lib / MooseX / InstanceTracking.pm 

            

              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
—
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101

              
package MooseX::InstanceTracking;
use Moose::Exporter;
our $VERSION = '0.06';
Moose::Exporter->setup_import_methods(
    class_metaroles => {
        class       => ['MooseX::InstanceTracking::Role::Class'],
    },
);
1;
__END__
=head1 NAME
MooseX::InstanceTracking - Trait for tracking all instances of a class
=head1 SYNOPSIS
    package Employee;
    use Moose;
    use MooseX::InstanceTracking;
    my $merrill = Employee->new;
    my $howard = Employee->new;
    Employee->meta->instances; # $merrill, $howard (or $howard, $merrill)
    Employee->meta->get_all_instances; # $merrill, $howard (or $howard, $merrill)
    package Employee::Chef;
    use Moose;
    extends 'Employee';
    my $kalin = Employee::Chef->new;
    Employee->meta->instances; # $merrill, $howard (or $howard, $merrill)
    Employee->meta->get_all_instances; # $merrill, $howard, $kalin (or $howard,  $merrill, $kalin)
=head1 DESCRIPTION
This extends your metaclass by providing instance tracking. Every object
that is instantiated will be tracked on the metaclass. This can be useful if
you need to interact with all the live objects for some reason.
There are two traits: a class trait, which adds the instance store and
accessors for it; and a constructor trait, which ensures that even instances
generated by inlined constructors are tracked.
=head1 METACLASS METHODS
=over 4
=item instances
Returns the B<unordered> set of instances of this direct class. Instances of
subclasses are not included in this set.
=item get_all_instances
Returns the B<unordered> set of instances of this direct class and all of its
subclasses.
=back
=head1 PRIVATE METACLASS METHODS
You should probably not call these methods. If you extend Moose by adding some
way to construct objects outside of L<Moose::Meta::Class/construct_instance>,
you I<are> crazy but you'll need to call these methods.
=over 4
=item _track_instance
Begins tracking the instance(s) passed.
=item _untrack_instance
Explicitly stops tracking the instance(s) passed. You do not need to call this
if your instance is garbage collected, since we use L<Set::Object::Weak>.
However if your instance leaves the class some other way, you may need to
explicitly call this. For example, this can happen in core Moose when an
instance is reblessed.
=back
=head1 AUTHOR
Shawn M Moore, C<sartak@bestpractical.com>
=head1 COPYRIGHT AND LICENSE
Copyright 2009 Shawn M Moore.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut