NAME

MooseX::InstanceTracking - Trait for tracking all instances of a class

SYNOPSIS

    package Employee;
    use Moose -traits => 'MooseX::InstanceTracking';
    
    my $jerry = Employee->new;
    my $george = Employee->new;
    
    Employee->meta->instances; # $jerry, $george (or $george, $jerry)
    Employee->meta->get_all_instances; # $jerry, $george (or $george, $jerry)
    
    
    package Employee::Chef;
    extends 'Employee';
    
    my $emerill = Employee::Chef->new;
    
    Employee->meta->instances; # $jerry, $george (or $george, $jerry)
    Employee->meta->get_all_instances; # $jerry, $george, $emerill

DESCRIPTION

This trait 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.

This trait has a limitation in that it does not work with make_immutable in the Moose::Meta::Class manpage. This is because a metaclass trait has no easy way to influence the code of inlined constructors, so we cannot begin tracking instances generated by the inlined constructor. To avoid introducing subtle bugs, this trait throws an error if you attempt to make_immutable. This does mean that instance construction will be slower.

PUBLIC METHODS

instances

Returns the unordered set of instances of this direct class. Instances of subclasses are not included in this set.

get_all_instances

Returns the unordered set of instances of this direct class and all of its subclasses.

PRIVATE METHODS

You should probably not call these methods. If you extend Moose by adding some way to construct objects outside of construct_instance in the Moose::Meta::Class manpage, you are crazy but you'll need to call these methods.

_track_instance

Begins tracking the instance(s) passed.

_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 the Set::Object::Weak manpage. 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.

AUTHOR

Shawn M Moore, sartak@bestpractical.com