sjohnston / class-xsaccessor Goto Github PK

NAME
    Class::XSAccessor - Generate fast XS accessors without runtime
    compilation

SYNOPSIS
      package MyClass;
      use Class::XSAccessor
        replace     => 1,   # Replace existing methods (if any)
        constructor => 'new',
        getters     => {
          get_foo => 'foo', # 'foo' is the hash key to access
          get_bar => 'bar',
        },
        setters => {
          set_foo => 'foo',
          set_bar => 'bar',
        },
        accessors => {
          foo => 'foo',
          bar => 'bar',
        },
        predicates => {
          has_foo => 'foo',
          has_bar => 'bar',
        }
        true  => [ 'is_token', 'is_whitespace' ],
        false => [ 'significant' ];
  
      # The imported methods are implemented in fast XS.
  
      # normal class code here.

    As of version 1.05, some alternative syntax forms are available:

      package MyClass;
  
      # Options can be passed as a HASH reference if you prefer it,
      # which can also help PerlTidy to flow the statement correctly.
      use Class::XSAccessor {
         # If the name => key values are always identical,
         # you can use the following shorthand.
         accessors => [ 'foo', 'bar' ],
      };

DESCRIPTION
    Class::XSAccessor implements fast read, write and read/write accessors
    in XS. Additionally, it can provide predicates such as "has_foo()" for
    testing whether the attribute "foo" is defined in the object. It only
    works with objects that are implemented as ordinary hashes.
    Class::XSAccessor::Array implements the same interface for objects that
    use arrays for their internal representation.

    Since version 0.10, the module can also generate simple constructors
    (implemented in XS) for you. Simply supply the "constructor =>
    'constructor_name'" option or the "constructors => ['new', 'create',
    'spawn']" option. These constructors do the equivalent of the following
    Perl code:

      sub new {
        my $class = shift;
        return bless { @_ }, ref($class)||$class;
      }

    That means they can be called on objects and classes but will not clone
    objects entirely. Parameters to "new()" are added to the object.

    The XS accessor methods are between 2.6 and 3.4 times faster than
    typical pure-perl accessors in some simple benchmarking. The lower
    factor applies to the potentially slightly obscure "sub set_foo_pp
    {$_[0]->{foo} = $_[1]}", so if you usually write clear code, a factor of
    two speed-up is a good estimate.

    The method names may be fully qualified. In the example of the synopsis,
    you could have written "MyClass::get_foo" instead of "get_foo". This
    way, you can install methods in classes other than the current class.
    See also: The "class" option below.

    By default, the setters return the new value that was set and the
    accessors (mutators) do the same. You can change this behaviour with the
    "chained" option, see below. The predicates obviously return a boolean.

    Since version 1.01, you can generate extremely simple methods which just
    return true or false (and always do so). If that seems like a really
    superfluous thing to you, then consider a large class hierarchy with
    interfaces such as PPI. This is implemented as the "true" and "false"
    options, see synopsis.

OPTIONS
    In addition to specifying the types and names of accessors, you can add
    options which modify behaviour. The options are specified as key/value
    pairs just as the accessor declaration. Example:

      use Class::XSAccessor
        getters => {
          get_foo => 'foo',
        },
        replace => 1;

    The list of available options is:

  replace
    Set this to a true value to prevent "Class::XSAccessor" from complaining
    about replacing existing subroutines.

  chained
    Set this to a true value to change the return value of setters and
    mutators (when called with an argument). If "chained" is enabled, the
    setters and accessors/mutators will return the object. Mutators called
    without an argument still return the value of the associated attribute.

    As with the other options, "chained" affects all methods generated in
    the same "use Class::XSAccessor ..." statement.

  class
    By default, the accessors are generated in the calling class. Using the
    "class" option, you can explicitly specify where the methods are to be
    generated.

CAVEATS
    Probably wouldn't work if your objects are *tied* hashes. But that's a
    strange thing to do anyway.

    Scary code exploiting strange XS features.

    If you think writing an accessor in XS should be a laughably simple
    exercise, then please contemplate how you could instantiate a new XS
    accessor for a new hash key that's only known at run-time. Note that
    compiling C code at run-time a la Inline::C is a no go.

    Threading. With version 1.00, a memory leak has been fixed that would
    leak a small amount of memory if you loaded "Class::XSAccessor"-based
    classes in a subthread that hadn't been loaded in the "main" thread
    before. If the subthread then terminated, a hash key and an int per
    associated method used ot be lost. Note that this mattered only if
    classes were only loaded in a sort of throw-away thread.

    In the new implementation as of 1.00, the memory will not be released
    again either in the above situation. But it will be recycled when the
    same class or a similar class is loaded again in any thread.

SEE ALSO
    Class::XSAccessor::Array

    AutoXS

AUTHOR
    Steffen Mueller <[email protected]>

    chocolateboy <[email protected]>

COPYRIGHT AND LICENSE
    Copyright (C) 2008-2010 by Steffen Mueller

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8 or, at your
    option, any later version of Perl 5 you may have available.