MooseX::Singleton(3) User Contributed Perl Documentation MooseX::Singleton(3)NAME
MooseX::Singleton - turn your Moose class into a singleton
VERSION
version 0.29
SYNOPSIS
package MyApp;
use MooseX::Singleton;
has env => (
is => 'rw',
isa => 'HashRef[Str]',
default => sub { \%ENV },
);
package main;
delete MyApp->env->{PATH};
my $instance = MyApp->instance;
my $same = MyApp->instance;
DESCRIPTION
A singleton is a class that has only one instance in an application. "MooseX::Singleton" lets you easily upgrade (or downgrade, as it
were) your Moose class to a singleton.
All you should need to do to transform your class is to change "use Moose" to "use MooseX::Singleton". This module uses metaclass roles to
do its magic, so it should cooperate with most other "MooseX" modules.
METHODS
A singleton class will have the following additional methods:
Singleton->instance
This returns the singleton instance for the given package. This method does not accept any arguments. If the instance does not yet exist,
it is created with its defaults values. This means that if your singleton requires arguments, calling "instance" will die if the object has
not already been initialized.
Singleton->initialize(%args)
This method can be called only once per class. It explicitly initializes the singleton object with the given arguments.
Singleton->_clear_instance
This clears the existing singleton instance for the class. Obviously, this is meant for use only inside the class itself.
Singleton->new
This method currently works like a hybrid of "initialize" and "instance". However, calling "new" directly will probably be deprecated in a
future release. Instead, call "initialize" or "instance" as appropriate.
BUGS
Please report any bugs or feature requests to "bug-moosex-singleton@rt.cpan.org", or through the web interface at <http://rt.cpan.org>. We
will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
SOME CODE STOLEN FROM
Anders Nor Berle <debolaz@gmail.com>
AND PATCHES FROM
Ricardo SIGNES <rjbs@cpan.org>
AUTHOR
Shawn M Moore <sartak@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Shawn M Moore.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
perl v5.18.2 2011-12-08 MooseX::Singleton(3)
Check Out this Related Man Page
Moose::Cookbook::Meta::Recipe7(3) User Contributed Perl Documentation Moose::Cookbook::Meta::Recipe7(3)NAME
Moose::Cookbook::Meta::Recipe7 - Creating a glob reference meta-instance class
VERSION
version 2.0205
SYNOPSIS
package My::Meta::Instance;
use Scalar::Util qw( weaken );
use Symbol qw( gensym );
use Moose;
extends 'Moose::Meta::Instance';
sub create_instance {
my $self = shift;
my $sym = gensym();
bless $sym, $self->_class_name;
}
sub clone_instance {
my ( $self, $instance ) = @_;
my $new_sym = gensym();
%{*$new_sym} = %{*$instance};
bless $new_sym, $self->_class_name;
}
sub get_slot_value {
my ( $self, $instance, $slot_name ) = @_;
return *$instance->{$slot_name};
}
sub set_slot_value {
my ( $self, $instance, $slot_name, $value ) = @_;
*$instance->{$slot_name} = $value;
}
sub deinitialize_slot {
my ( $self, $instance, $slot_name ) = @_;
delete *$instance->{$slot_name};;
}
sub is_slot_initialized {
my ( $self, $instance, $slot_name, $value ) = @_;
exists *$instance->{$slot_name};;
}
sub weaken_slot_value {
my ( $self, $instance, $slot_name ) = @_;
weaken *$instance->{$slot_name};;
}
sub inline_create_instance {
my ( $self, $class_variable ) = @_;
return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
}
sub inline_slot_access {
my ( $self, $instance, $slot_name ) = @_;
return '*{' . $instance . '}->{' . $slot_name . '}';
}
package MyApp::User;
use metaclass 'Moose::Meta::Class' =>
( instance_metaclass => 'My::Meta::Instance' );
use Moose;
has 'name' => (
is => 'rw',
isa => 'Str',
);
has 'email' => (
is => 'rw',
isa => 'Str',
);
DESCRIPTION
This recipe shows how to build your own meta-instance. The meta instance is the metaclass that creates object instances and helps manages
access to attribute slots.
In this example, we're creating a meta-instance that is based on a glob reference rather than a hash reference. This example is largely
based on the Piotr Roszatycki's MooseX::GlobRef module.
Our class is a subclass of Moose::Meta::Instance, which creates hash reference based objects. We need to override all the methods which
make assumptions about the object's data structure.
The first method we override is "create_instance":
sub create_instance {
my $self = shift;
my $sym = gensym();
bless $sym, $self->_class_name;
}
This returns an glob reference which has been blessed into our meta-instance's associated class.
We also override "clone_instance" to create a new array reference:
sub clone_instance {
my ( $self, $instance ) = @_;
my $new_sym = gensym();
%{*$new_sym} = %{*$instance};
bless $new_sym, $self->_class_name;
}
After that, we have a series of methods which mediate access to the object's slots (attributes are stored in "slots"). In the default
instance class, these expect the object to be a hash reference, but we need to change this to expect a glob reference instead.
sub get_slot_value {
my ( $self, $instance, $slot_name ) = @_;
*$instance->{$slot_name};;
}
This level of indirection probably makes our instance class slower than the default. However, when attribute access is inlined, this lookup
will be cached:
sub inline_create_instance {
my ( $self, $class_variable ) = @_;
return 'do { my $sym = Symbol::gensym(); bless $sym, ' . $class_variable . ' }';
}
The code snippet that the "inline_slot_access" method returns will get "eval"'d once per attribute.
Finally, we use this meta-instance in our "MyApp::User" class:
use metaclass 'Moose::Meta::Class' =>
( instance_metaclass => 'My::Meta::Instance' );
We actually don't recommend the use of metaclass in most cases. However, the other ways of using alternate metaclasses are more complex,
and would complicate our example code unnecessarily.
CONCLUSION
This recipe shows how to create your own meta-instance class. It's unlikely that you'll need to do this yourself, but it's interesting to
take a peek at how Moose works under the hood.
SEE ALSO
There are a few meta-instance class extensions on CPAN:
o MooseX::Singleton
This module extends the instance class in order to ensure that the object is a singleton. The instance it uses is still a blessed hash
reference.
o MooseX::GlobRef
This module makes the instance a blessed glob reference. This lets you use a handle as an object instance.
AUTHOR
Stevan Little <stevan@iinteractive.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Infinity Interactive, Inc..
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
perl v5.12.5 2011-09-06 Moose::Cookbook::Meta::Recipe7(3)