{ "content": [ { "type": "text", "text": "# Class::XSAccessor::Array (perldoc)\n\n## NAME\n\nClass::XSAccessor::Array - Generate fast XS accessors without runtime compilation\n\n## SYNOPSIS\n\npackage MyClassUsingArraysAsInternalStorage;\nuse Class::XSAccessor::Array\nconstructor => 'new',\ngetters => {\ngetfoo => 0, # 0 is the array index to access\ngetbar => 1,\n},\nsetters => {\nsetfoo => 0,\nsetbar => 1,\n},\naccessors => { # a mutator\nbuz => 2,\n},\npredicates => { # test for definedness\nhasbuz => 2,\n},\nlvalueaccessors => { # see below\nbaz => 3,\n},\ntrue => [ 'istoken', 'iswhitespace' ],\nfalse => [ 'significant' ];\n# The imported methods are implemented in fast XS.\n# normal class code here.\nAs of version 1.05, some alternative syntax forms are available:\npackage MyClass;\n# Options can be passed as a HASH reference if you prefer it,\n# which can also help PerlTidy to flow the statement correctly.\nuse Class::XSAccessor {\ngetters => {\ngetfoo => 0,\ngetbar => 1,\n},\n};\n\n## DESCRIPTION\n\nThe module implements fast XS accessors both for getting at and setting an object attribute.\nAdditionally, the module supports mutators and simple predicates (\"hasfoo()\" like tests for\ndefinedness of an attributes). The module works only with objects that are implemented as\narrays. Using it on hash-based objects is bound to make your life miserable. Refer to\nClass::XSAccessor for an implementation that works with hash-based objects.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **OPTIONS**\n- **LVALUES**\n- **CAVEATS**\n- **SEE ALSO**\n- **AUTHOR**\n- **COPYRIGHT AND LICENSE**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "Class::XSAccessor::Array", "section": "", "mode": "perldoc", "summary": "Class::XSAccessor::Array - Generate fast XS accessors without runtime compilation", "synopsis": "package MyClassUsingArraysAsInternalStorage;\nuse Class::XSAccessor::Array\nconstructor => 'new',\ngetters => {\ngetfoo => 0, # 0 is the array index to access\ngetbar => 1,\n},\nsetters => {\nsetfoo => 0,\nsetbar => 1,\n},\naccessors => { # a mutator\nbuz => 2,\n},\npredicates => { # test for definedness\nhasbuz => 2,\n},\nlvalueaccessors => { # see below\nbaz => 3,\n},\ntrue => [ 'istoken', 'iswhitespace' ],\nfalse => [ 'significant' ];\n# The imported methods are implemented in fast XS.\n# normal class code here.\nAs of version 1.05, some alternative syntax forms are available:\npackage MyClass;\n# Options can be passed as a HASH reference if you prefer it,\n# which can also help PerlTidy to flow the statement correctly.\nuse Class::XSAccessor {\ngetters => {\ngetfoo => 0,\ngetbar => 1,\n},\n};", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 40, "subsections": [] }, { "name": "DESCRIPTION", "lines": 36, "subsections": [] }, { "name": "OPTIONS", "lines": 28, "subsections": [] }, { "name": "LVALUES", "lines": 17, "subsections": [] }, { "name": "CAVEATS", "lines": 18, "subsections": [] }, { "name": "SEE ALSO", "lines": 4, "subsections": [] }, { "name": "AUTHOR", "lines": 4, "subsections": [] }, { "name": "COPYRIGHT AND LICENSE", "lines": 6, "subsections": [] } ], "sections": { "NAME": { "content": "Class::XSAccessor::Array - Generate fast XS accessors without runtime compilation\n", "subsections": [] }, "SYNOPSIS": { "content": "package MyClassUsingArraysAsInternalStorage;\nuse Class::XSAccessor::Array\nconstructor => 'new',\ngetters => {\ngetfoo => 0, # 0 is the array index to access\ngetbar => 1,\n},\nsetters => {\nsetfoo => 0,\nsetbar => 1,\n},\naccessors => { # a mutator\nbuz => 2,\n},\npredicates => { # test for definedness\nhasbuz => 2,\n},\nlvalueaccessors => { # see below\nbaz => 3,\n},\ntrue => [ 'istoken', 'iswhitespace' ],\nfalse => [ 'significant' ];\n\n# The imported methods are implemented in fast XS.\n\n# normal class code here.\n\nAs of version 1.05, some alternative syntax forms are available:\n\npackage MyClass;\n\n# Options can be passed as a HASH reference if you prefer it,\n# which can also help PerlTidy to flow the statement correctly.\nuse Class::XSAccessor {\ngetters => {\ngetfoo => 0,\ngetbar => 1,\n},\n};\n", "subsections": [] }, "DESCRIPTION": { "content": "The module implements fast XS accessors both for getting at and setting an object attribute.\nAdditionally, the module supports mutators and simple predicates (\"hasfoo()\" like tests for\ndefinedness of an attributes). The module works only with objects that are implemented as\narrays. Using it on hash-based objects is bound to make your life miserable. Refer to\nClass::XSAccessor for an implementation that works with hash-based objects.\n\nA simple benchmark showed a significant performance advantage over writing accessors in Perl.\n\nSince version 0.10, the module can also generate simple constructors (implemented in XS) for\nyou. Simply supply the \"constructor => 'constructorname'\" option or the \"constructors =>\n['new', 'create', 'spawn']\" option. These constructors do the equivalent of the following Perl\ncode:\n\nsub new {\nmy $class = shift;\nreturn bless [], ref($class)||$class;\n}\n\nThat means they can be called on objects and classes but will not clone objects entirely. Note\nthat any parameters to new() will be discarded! If there is a better idiom for array-based\nobjects, let me know.\n\nWhile generally more obscure than hash-based objects, objects using blessed arrays as internal\nrepresentation are a bit faster as its somewhat faster to access arrays than hashes.\nAccordingly, this module is slightly faster (~10-15%) than Class::XSAccessor, which works on\nhash-based objects.\n\nThe method names may be fully qualified. In the example of the synopsis, you could have written\n\"MyClass::getfoo\" instead of \"getfoo\". This way, you can install methods in classes other than\nthe current class. See also: The \"class\" option below.\n\nSince version 1.01, you can generate extremely simple methods which just return true or false\n(and always do so). If that seems like a really superfluous thing to you, then think of a large\nclass hierarchy with interfaces such as PPI. This is implemented as the \"true\" and \"false\"\noptions, see synopsis.\n", "subsections": [] }, "OPTIONS": { "content": "In addition to specifying the types and names of accessors, you can add options which modify\nbehaviour. The options are specified as key/value pairs just as the accessor declaration.\nExample:\n\nuse Class::XSAccessor::Array\ngetters => {\ngetfoo => 0,\n},\nreplace => 1;\n\nThe list of available options is:\n\nreplace\nSet this to a true value to prevent \"Class::XSAccessor::Array\" from complaining about replacing\nexisting subroutines.\n\nchained\nSet this to a true value to change the return value of setters and mutators (when called with an\nargument). If \"chained\" is enabled, the setters and accessors/mutators will return the object.\nMutators called without an argument still return the value of the associated attribute.\n\nAs with the other options, \"chained\" affects all methods generated in the same \"use\nClass::XSAccessor::Array ...\" statement.\n\nclass\nBy default, the accessors are generated in the calling class. Using the \"class\" option, you can\nexplicitly specify where the methods are to be generated.\n", "subsections": [] }, "LVALUES": { "content": "Support for lvalue accessors via the keyword \"lvalueaccessors\" was added in version 1.08. At\nthis point, THEY ARE CONSIDERED HIGHLY EXPERIMENTAL. Furthermore, their performance hasn't been\nbenchmarked yet.\n\nThe following example demonstrates an lvalue accessor:\n\npackage Address;\nuse Class::XSAccessor\nconstructor => 'new',\nlvalueaccessors => { zipcode => 0 };\n\npackage main;\nmy $address = Address->new(2);\nprint $address->zipcode, \"\\n\"; # prints 2\n$address->zipcode = 76135; # <--- This is it!\nprint $address->zipcode, \"\\n\"; # prints 76135\n", "subsections": [] }, "CAVEATS": { "content": "Probably wouldn't work if your objects are *tied*. But that's a strange thing to do anyway.\n\nScary code exploiting strange XS features.\n\nIf you think writing an accessor in XS should be a laughably simple exercise, then please\ncontemplate how you could instantiate a new XS accessor for a new hash key or array index that's\nonly known at run-time. Note that compiling C code at run-time a la Inline::C is a no go.\n\nThreading. With version 1.00, a memory leak has been fixed that would leak a small amount of\nmemory if you loaded \"Class::XSAccessor\"-based classes in a subthread that hadn't been loaded in\nthe \"main\" thread before. If the subthread then terminated, a hash key and an int per associated\nmethod used to be lost. Note that this mattered only if classes were only loaded in a sort of\nthrow-away thread.\n\nIn the new implementation as of 1.00, the memory will not be released again either in the above\nsituation. But it will be recycled when the same class or a similar class is loaded again in any\nthread.\n", "subsections": [] }, "SEE ALSO": { "content": "Class::XSAccessor\n\nAutoXS\n", "subsections": [] }, "AUTHOR": { "content": "Steffen Mueller \n\nchocolateboy \n", "subsections": [] }, "COPYRIGHT AND LICENSE": { "content": "Copyright (C) 2008, 2009, 2010, 2011, 2012, 2013 by Steffen Mueller\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself, either Perl version 5.8 or, at your option, any later version of Perl 5 you may\nhave available.\n", "subsections": [] } } } }