---
name: "MooseX::XSAccessor"
section: "3pm"
platform: "linux"
package: "libmoosex-xsaccessor-perl"
version: "0.010-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/MooseX::XSAccessor"
---

# MooseX::XSAccessor(3pm)

use Class::XSAccessor to speed up Moose accessors

## 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.