NAME

       MooseX::XSAccessor - use Class::XSAccessor to speed up Moose accessors

SYNOPSIS

          package MyClass;

          use Moose;
          use MooseX::XSAccessor;

          has foo => (...);

DESCRIPTION

       This module accelerates Moose-generated accessor, reader, writer and predicate methods using
       Class::XSAccessor. You get a speed-up for no extra effort. It is automatically applied to every attribute
       in the class.

       The use of the following features of Moose attributes prevents a reader from being accelerated:

       •   Lazy builder or lazy default.

       •   Auto-deref. (Does anybody use this anyway??)

       The use of the following features prevents a writer from being accelerated:

       •   Type constraints (except "Any"; "Any" is effectively a no-op).

       •   Triggers

       •   Weak references

       An "rw" accessor is effectively a reader and a writer glued together, so both of the above lists apply.

       Predicates can always be accelerated, provided you're using Class::XSAccessor 1.17 or above.

       Clearers can not be accelerated (as of current versions of Class::XSAccessor).

   Functions
       This module also provides one function, which is not exported so needs to be called by its full name.

       "MooseX::XSAccessor::is_xs($sub)"
           Returns a boolean indicating whether a sub is an XSUB.

           $sub  may  be  a  coderef,  Class::MOP::Method  object,  or  a  qualified  sub name as a string (e.g.
           "MyClass::foo").

           This function doesn't just work with accessors, but should be able to detect the  difference  between
           Perl and XS subs in general. (It may not be 100% reliable though.)

   Chained accessors and writers
       MooseX::XSAccessor can detect chained accessors and writers created using MooseX::Attribute::Chained, and
       can accelerate those too.

          package Local::Class;
          use Moose;
          use MooseX::XSAccessor;
          use MooseX::Attribute::Chained;

          has foo => (traits => ["Chained"], is => "rw");
          has bar => (traits => ["Chained"], is => "ro", writer => "_set_bar");
          has baz => (                       is => "rw");  # not chained

          my $obj = "Local::Class"->new;
          $obj->foo(1)->_set_bar(2);
          print $obj->dump;

   Lvalue accessors
       MooseX::XSAccessor  will  detect  lvalue  accessors created with MooseX::LvalueAttribute and, by default,
       skip accelerating them.

       However, by setting $MooseX::XSAccessor::LVALUE to true (preferably using the "local" Perl keyword),  you
       can  force  it  to  accelerate  those  too.  This  introduces  a  visible  change  in  behaviour  though.
       MooseX::LvalueAttribute accessors normally allow two patterns for setting the value:

          $obj->foo = 42;   # as an lvalue
          $obj->foo(42);    # as a method call

       However,  once  accelerated,  they  may  only  be  set  as  an  lvalue.    For   this   reason,   setting
       $MooseX::XSAccessor::LVALUE to true is considered an experimental feature.

HINTS

       •   Make  attributes  read-only  when  possible. This means that type constraints and coercions will only
           apply to the constructor, not the accessors, enabling the accessors to be accelerated.

       •   If you do need a read-write attribute, consider making the main  accessor  read-only,  and  having  a
           separate writer method. (Like MooseX::SemiAffordanceAccessor.)

       •   Make defaults eager instead of lazy when possible, allowing your readers to be accelerated.

       •   If you need to accelerate just a specific attribute, apply the attribute trait directly:

              package MyClass;

              use Moose;

              has foo => (
                 traits => ["MooseX::XSAccessor::Trait::Attribute"],
                 ...,
              );

       •   If you don't want to add a dependency on MooseX::XSAccessor, but do want to use it if it's available,
           the following code will use it optionally:

              package MyClass;

              use Moose;
              BEGIN { eval "use MooseX::XSAccessor" };

              has foo => (...);

CAVEATS

       •   Calling a writer method without a parameter in Moose does not raise an exception:

              $person->set_name();    # sets name attribute to "undef"

           However, this is a fatal error in Class::XSAccessor.

       •   MooseX::XSAccessor  does not play nice with attribute traits that alter accessor behaviour, or define
           additional    accessors    for    attributes.     MooseX::SetOnce    is    an    example     thereof.
           MooseX::Attribute::Chained is handled as a special case.

       •   MooseX::XSAccessor   only   works   on   blessed   hash   storage;   not  e.g.   MooseX::ArrayRef  or
           MooseX::InsideOut. MooseX::XSAccessor is usually able to detect such situations and  silently  switch
           itself off.

BUGS

       Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=MooseX-XSAccessor>.

SEE ALSO

       MooseX::XSAccessor::Trait::Attribute.

       Moose, Moo, Class::XSAccessor.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2013, 2017 by Toby Inkster.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

DISCLAIMER OF WARRANTIES

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT  ANY  EXPRESS  OR  IMPLIED  WARRANTIES,  INCLUDING,  WITHOUT
       LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.36.0                                       2022-11-29                            MooseX::XSAccessor(3pm)