plucky (3) MooseX::XSAccessor.3pm.gz

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 <https://github.com/tobyink/p5-moosex-xsaccessor/issues>.

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, 2022 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.