.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Class::MOP::Instance 3"
.TH Class::MOP::Instance 3 "2021-11-07" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Class::MOP::Instance \- Instance Meta Object
.SH "VERSION"
.IX Header "VERSION"
version 2.2201
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Instance Protocol controls the creation of object instances, and
the storage of attribute values in those instances.
.PP
Using this \s-1API\s0 directly in your own code violates encapsulation, and
we recommend that you use the appropriate APIs in Class::MOP::Class
and Class::MOP::Attribute instead. Those APIs in turn call the
methods in this class as appropriate.
.PP
This class also participates in generating inlined code by providing
snippets of code to access an object instance.
.SH "METHODS"
.IX Header "METHODS"
.SS "Object construction"
.IX Subsection "Object construction"
.IP "\fBClass::MOP::Instance\->new(%options)\fR" 4
.IX Item "Class::MOP::Instance->new(%options)"
This method creates a new meta-instance object.
.Sp
It accepts the following keys in \f(CW%options\fR:
.RS 4
.IP "\(bu" 8
associated_metaclass
.Sp
The Class::MOP::Class object for which instances will be created.
.IP "\(bu" 8
attributes
.Sp
An array reference of Class::MOP::Attribute objects. These are the
attributes which can be stored in each instance.
.RE
.RS 4
.RE
.SS "Creating and altering instances"
.IX Subsection "Creating and altering instances"
.IP "\fB\f(CB$metainstance\fB\->create_instance\fR" 4
.IX Item "$metainstance->create_instance"
This method returns a reference blessed into the associated
metaclass's class.
.Sp
The default is to use a hash reference. Subclasses can override this.
.IP "\fB\f(CB$metainstance\fB\->clone_instance($instance)\fR" 4
.IX Item "$metainstance->clone_instance($instance)"
Given an instance, this method creates a new object by making
\&\fIshallow\fR clone of the original.
.SS "Introspection"
.IX Subsection "Introspection"
.IP "\fB\f(CB$metainstance\fB\->associated_metaclass\fR" 4
.IX Item "$metainstance->associated_metaclass"
This returns the Class::MOP::Class object associated with the
meta-instance object.
.IP "\fB\f(CB$metainstance\fB\->get_all_slots\fR" 4
.IX Item "$metainstance->get_all_slots"
This returns a list of slot names stored in object instances. In
almost all cases, slot names correspond directly attribute names.
.IP "\fB\f(CB$metainstance\fB\->is_valid_slot($slot_name)\fR" 4
.IX Item "$metainstance->is_valid_slot($slot_name)"
This will return true if \f(CW$slot_name\fR is a valid slot name.
.IP "\fB\f(CB$metainstance\fB\->get_all_attributes\fR" 4
.IX Item "$metainstance->get_all_attributes"
This returns a list of attributes corresponding to the attributes
passed to the constructor.
.SS "Operations on Instance Structures"
.IX Subsection "Operations on Instance Structures"
It's important to understand that the meta-instance object is a
different entity from the actual instances it creates. For this
reason, any operations on the \f(CW$instance_structure\fR always require
that the object instance be passed to the method.
.IP "\fB\f(CB$metainstance\fB\->get_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->get_slot_value($instance_structure, $slot_name)"
.PD 0
.IP "\fB\f(CB$metainstance\fB\->set_slot_value($instance_structure, \f(CB$slot_name\fB, \f(CB$value\fB)\fR" 4
.IX Item "$metainstance->set_slot_value($instance_structure, $slot_name, $value)"
.IP "\fB\f(CB$metainstance\fB\->initialize_slot($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->initialize_slot($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->deinitialize_slot($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->deinitialize_slot($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->initialize_all_slots($instance_structure)\fR" 4
.IX Item "$metainstance->initialize_all_slots($instance_structure)"
.IP "\fB\f(CB$metainstance\fB\->deinitialize_all_slots($instance_structure)\fR" 4
.IX Item "$metainstance->deinitialize_all_slots($instance_structure)"
.IP "\fB\f(CB$metainstance\fB\->is_slot_initialized($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->is_slot_initialized($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->weaken_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->weaken_slot_value($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->slot_value_is_weak($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->slot_value_is_weak($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->strengthen_slot_value($instance_structure, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->strengthen_slot_value($instance_structure, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->rebless_instance_structure($instance_structure, \f(CB$new_metaclass\fB)\fR" 4
.IX Item "$metainstance->rebless_instance_structure($instance_structure, $new_metaclass)"
.PD
The exact details of what each method does should be fairly obvious
from the method name.
.SS "Inlinable Instance Operations"
.IX Subsection "Inlinable Instance Operations"
.IP "\fB\f(CB$metainstance\fB\->is_inlinable\fR" 4
.IX Item "$metainstance->is_inlinable"
This is a boolean that indicates whether or not slot access operations
can be inlined. By default it is true, but subclasses can override
this.
.IP "\fB\f(CB$metainstance\fB\->inline_create_instance($class_variable)\fR" 4
.IX Item "$metainstance->inline_create_instance($class_variable)"
This method expects a string that, \fIwhen inlined\fR, will become a
class name. This would literally be something like \f(CW\*(Aq$class\*(Aq\fR, not an
actual class name.
.Sp
It returns a snippet of code that creates a new object for the
class. This is something like \f(CW\*(C` bless {}, $class_name \*(C'\fR.
.IP "\fB\f(CB$metainstance\fB\->inline_get_is_lvalue\fR" 4
.IX Item "$metainstance->inline_get_is_lvalue"
Returns whether or not \f(CW\*(C`inline_get_slot_value\*(C'\fR is a valid lvalue. This can be
used to do extra optimizations when generating inlined methods.
.IP "\fB\f(CB$metainstance\fB\->inline_slot_access($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_slot_access($instance_variable, $slot_name)"
.PD 0
.IP "\fB\f(CB$metainstance\fB\->inline_get_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_get_slot_value($instance_variable, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->inline_set_slot_value($instance_variable, \f(CB$slot_name\fB, \f(CB$value\fB)\fR" 4
.IX Item "$metainstance->inline_set_slot_value($instance_variable, $slot_name, $value)"
.IP "\fB\f(CB$metainstance\fB\->inline_initialize_slot($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_initialize_slot($instance_variable, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->inline_deinitialize_slot($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_deinitialize_slot($instance_variable, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->inline_is_slot_initialized($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_is_slot_initialized($instance_variable, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->inline_weaken_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_weaken_slot_value($instance_variable, $slot_name)"
.IP "\fB\f(CB$metainstance\fB\->inline_strengthen_slot_value($instance_variable, \f(CB$slot_name\fB)\fR" 4
.IX Item "$metainstance->inline_strengthen_slot_value($instance_variable, $slot_name)"
.PD
These methods all expect two arguments. The first is the name of a
variable, than when inlined, will represent the object
instance. Typically this will be a literal string like \f(CW\*(Aq$_[0]\*(Aq\fR.
.Sp
The second argument is a slot name.
.Sp
The method returns a snippet of code that, when inlined, performs some
operation on the instance.
.IP "\fB\f(CB$metainstance\fB\->inline_rebless_instance_structure($instance_variable, \f(CB$class_variable\fB)\fR" 4
.IX Item "$metainstance->inline_rebless_instance_structure($instance_variable, $class_variable)"
This takes the name of a variable that will, when inlined, represent the object
instance, and the name of a variable that will represent the class to rebless
into, and returns code to rebless an instance into a class.
.SS "Introspection"
.IX Subsection "Introspection"
.IP "\fBClass::MOP::Instance\->meta\fR" 4
.IX Item "Class::MOP::Instance->meta"
This will return a Class::MOP::Class instance for this class.
.Sp
It should also be noted that Class::MOP will actually bootstrap
this module by installing a number of attribute meta-objects into its
metaclass.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Stevan Little <stevan@cpan.org>
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.IP "\(bu" 4
Jesse Luehrs <doy@cpan.org>
.IP "\(bu" 4
Shawn M Moore <sartak@cpan.org>
.IP "\(bu" 4
יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
.IP "\(bu" 4
Karen Etheridge <ether@cpan.org>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.IP "\(bu" 4
Hans Dieter Pearcey <hdp@cpan.org>
.IP "\(bu" 4
Chris Prather <chris@prather.org>
.IP "\(bu" 4
Matt S Trout <mstrout@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2006 by Infinity Interactive, Inc.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.