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.