Current File : /home/opti/perl/usr/man/man3/Type::Tiny::Manual::Optimization.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
. if \nF \{
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Type::Tiny::Manual::Optimization 3"
.TH Type::Tiny::Manual::Optimization 3 "2018-07-29" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Type::Tiny::Manual::Optimization \- squeeze the most out of your CPU
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Various tips to help you squeeze the most out of your \s-1CPU.\s0
.SS "\s-1XS\s0"
.IX Subsection "XS"
The simplest thing you can do to increase performance of many of
the built-in type constraints is to install Type::Tiny::XS, a
set of ultra-fast type constraint checks implemented in C.
.PP
Type::Tiny will attempt to load Type::Tiny::XS and use its
type checks. If Type::Tiny::XS is not available, it will then
try to use Mouse \fBif it is already loaded\fR, but Type::Tiny
won't attempt to load Mouse for you.
.PP
\fITypes that can be accelerated by Type::Tiny::XS\fR
.IX Subsection "Types that can be accelerated by Type::Tiny::XS"
.PP
The following simple type constraints from Types::Standard will
be accelerated by Type::Tiny::XS: \f(CW\*(C`Any\*(C'\fR, \f(CW\*(C`ArrayRef\*(C'\fR, \f(CW\*(C`Bool\*(C'\fR,
\&\f(CW\*(C`ClassName\*(C'\fR, \f(CW\*(C`CodeRef\*(C'\fR, \f(CW\*(C`Defined\*(C'\fR, \f(CW\*(C`FileHandle\*(C'\fR, \f(CW\*(C`GlobRef\*(C'\fR,
\&\f(CW\*(C`HashRef\*(C'\fR, \f(CW\*(C`Int\*(C'\fR, \f(CW\*(C`Item\*(C'\fR, \f(CW\*(C`Object\*(C'\fR, \f(CW\*(C`Map\*(C'\fR, \f(CW\*(C`Ref\*(C'\fR, \f(CW\*(C`ScalarRef\*(C'\fR,
\&\f(CW\*(C`Str\*(C'\fR, \f(CW\*(C`Tuple\*(C'\fR, \f(CW\*(C`Undef\*(C'\fR, and \f(CW\*(C`Value\*(C'\fR. (Note that \f(CW\*(C`Num\*(C'\fR and
\&\f(CW\*(C`RegexpRef\*(C'\fR are \fBnot\fR on that list.)
.PP
The parameterized form of \f(CW\*(C`Ref\*(C'\fR cannot be accelerated.
.PP
The parameterized forms of \f(CW\*(C`ArrayRef\*(C'\fR, \f(CW\*(C`HashRef\*(C'\fR, and \f(CW\*(C`Map\*(C'\fR can be
accelerated only if their parameters are.
.PP
The parameterized form of \f(CW\*(C`Tuple\*(C'\fR can be accelerated if its
parameters are, it has no \f(CW\*(C`Optional\*(C'\fR components, and it does not use
\&\f(CW\*(C`slurpy\*(C'\fR.
.PP
Certain type constraints may benefit partially from Type::Tiny::XS.
For example, \f(CW\*(C`RoleName\*(C'\fR inherits from \f(CW\*(C`ClassName\*(C'\fR, so part of the
type check will be conducted by Type::Tiny::XS.
.PP
The parameterized \f(CW\*(C`InstanceOf\*(C'\fR, \f(CW\*(C`HasMethods\*(C'\fR, and \f(CW\*(C`Enum\*(C'\fR type
constraints will be accelerated. So will Type::Tiny::Class,
Type::Tiny::Duck, and Type::Tiny::Enum objects. (But enums will
only be accelerated if the list of allowed string values consist
entirely of word characters and hyphens \- that is:
\&\f(CW\*(C`not grep /[^\ew\-]/, @values\*(C'\fR.)
.PP
The \f(CW\*(C`PositiveInt\*(C'\fR and \f(CW\*(C`PositiveOrZeroInt\*(C'\fR type constraints from
Types::Common::Numeric will be accelerated, as will the
\&\f(CW\*(C`NonEmptyStr\*(C'\fR type constraint from Types::Common::String.
.PP
Type::Tiny::Union and Type::Tiny::Intersection will also be
accelerated if their constituent type constraints are.
.PP
\fITypes that can be accelerated by Mouse\fR
.IX Subsection "Types that can be accelerated by Mouse"
.PP
The following simple type constraints from Types::Standard will
be accelerated by Type::Tiny::XS: \f(CW\*(C`Any\*(C'\fR, \f(CW\*(C`ArrayRef\*(C'\fR, \f(CW\*(C`Bool\*(C'\fR,
\&\f(CW\*(C`ClassName\*(C'\fR, \f(CW\*(C`CodeRef\*(C'\fR, \f(CW\*(C`Defined\*(C'\fR, \f(CW\*(C`FileHandle\*(C'\fR, \f(CW\*(C`GlobRef\*(C'\fR,
\&\f(CW\*(C`HashRef\*(C'\fR, \f(CW\*(C`Ref\*(C'\fR, \f(CW\*(C`ScalarRef\*(C'\fR, \f(CW\*(C`Str\*(C'\fR, \f(CW\*(C`Undef\*(C'\fR, and \f(CW\*(C`Value\*(C'\fR.
(Note that \f(CW\*(C`Item\*(C'\fR, \f(CW\*(C`Num\*(C'\fR, \f(CW\*(C`Int\*(C'\fR, \f(CW\*(C`Object\*(C'\fR, and \f(CW\*(C`RegexpRef\*(C'\fR
are \fBnot\fR on that list.)
.PP
The parameterized form of \f(CW\*(C`Ref\*(C'\fR cannot be accelerated.
.PP
The parameterized forms of \f(CW\*(C`ArrayRef\*(C'\fR and \f(CW\*(C`HashRef\*(C'\fR can be
accelerated only if their parameters are.
.PP
Certain type constraints may benefit partially from Mouse. For
example, \f(CW\*(C`RoleName\*(C'\fR inherits from \f(CW\*(C`ClassName\*(C'\fR, so part of the
type check will be conducted by Mouse.
.PP
The parameterized \f(CW\*(C`InstanceOf\*(C'\fR and \f(CW\*(C`HasMethods\*(C'\fR type constraints
will be accelerated. So will Type::Tiny::Class and
Type::Tiny::Duck objects.
.SS "Common Sense"
.IX Subsection "Common Sense"
The \f(CW\*(C`HashRef[ArrayRef]\*(C'\fR type constraint can probably be checked
faster than \f(CW\*(C`HashRef[ArrayRef[Num]]\*(C'\fR. If you find yourself using
very complex and slow type constraints, you should consider switching
to simpler and faster ones. (Though this means you have to place a
little more trust in your caller to not supply you with bad data.)
.PP
(A counter-intuitive exception to this: even though \f(CW\*(C`Int\*(C'\fR is more
restrictive than \f(CW\*(C`Num\*(C'\fR, in most circumstances \f(CW\*(C`Int\*(C'\fR checks will run
faster.)
.SS "Inlining Type Constraints"
.IX Subsection "Inlining Type Constraints"
If your type constraint can be inlined, this can not only speed up
Type::Tiny's own checks and coercions, it may also allow your type constraint
to be inlined into generated methods such as Moose attribute accessors.
.PP
All of the constraints from \f(CW\*(C`Types::Standard\*(C'\fR can be inlined, as can enum,
class_type, role_type and duck_type constraints. Union and intersection
constraints can be inlined if their sub-constraints can be. So if you can
define your own types purely in terms of these types, you automatically
get inlining:
.PP
.Vb 4
\& declare HashLike, as union [
\& Ref["HASH"],
\& Overload["&{}"],
\& ];
.Ve
.PP
However, sometimes these base types are not powerful enough and you'll need
to write a constraint coderef:
.PP
.Vb 2
\& declare NonEmptyHash, as HashLike,
\& where { scalar values %$_ };
.Ve
.PP
\&... and you've suddenly sacrificed a lot of speed.
.PP
Inlining to the rescue! You can define an inlining coderef which will be
passed two parameters: the constraint itself and a variable name as a string.
For example, the variable name might be \f(CW\*(Aq$_\*(Aq\fR or \f(CW\*(Aq$_[0]\*(Aq\fR.
Your coderef should return a Perl expression string, interpolating that
variable name.
.PP
.Vb 10
\& declare NonEmptyHash, as HashLike,
\& where { scalar values %$_ },
\& inline_as {
\& my ($constraint, $varname) = @_;
\& return sprintf(
\& \*(Aq%s and scalar values %%{%s}\*(Aq,
\& $constraint\->parent\->inline_check($varname),
\& $varname,
\& );
\& };
.Ve
.PP
The Perl expression could be inlined within a function or a \f(CW\*(C`if\*(C'\fR clause or
potentially anywhere, so it really must be an expression, not a statement.
It should not \f(CW\*(C`return\*(C'\fR or \f(CW\*(C`exit\*(C'\fR and probably shouldn't \f(CW\*(C`die\*(C'\fR. (If you
need loops and so on, you can output a \f(CW\*(C`do\*(C'\fR block.)
.PP
Note that if you're subtyping an existing type constraint, your \f(CW\*(C`inline_as\*(C'\fR
block is also responsible for checking the parent type's constraint. This
can be done quite easily, as shown in the example above.
.PP
Note that defining a type constraint in terms of a constraint coderef and an
inlining coderef can be a little repetitive. Sub::Quote provides an
alternative that reduces repetition (though the inlined code might not be as
compact/good/fast).
.PP
.Vb 2
\& declare NonEmptyHash, as HashLike,
\& constraint => quote_sub q{ scalar values %$_ };
.Ve
.PP
Aside: it's been pointed out that \*(L"might not be as fast\*(R" above is a bit
hand-wavy. When Type::Tiny does inlining from Sub::Quote coderefs, it needs
to inline all the ancestor type constraints, and smush them together with
\&\f(CW\*(C`&&\*(C'\fR. This may result in duplicate checks. For example, if 'MyArray'
inherits from 'MyRef' which inherits from 'MyDef', the inlined code might
end up as:
.PP
.Vb 3
\& defined($_) # check MyDef
\& && ref($_) # check MyRef
\& && ref($_) eq \*(AqARRAY\*(Aq # check MyArray
.Ve
.PP
When just the last check would have been sufficient. A custom \f(CW\*(C`inline_as\*(C'\fR
allows you finer control over how the type constraint is inlined.
.SS "Optimizing Coercions"
.IX Subsection "Optimizing Coercions"
Coercions are often defined using coderefs:
.PP
.Vb 4
\& PathTiny\->plus_coercions(
\& Str, sub { "Path::Tiny"\->new($_) },
\& Undef, sub { "Path::Tiny"\->new("/etc/myapp/default.conf") },
\& );
.Ve
.PP
But you can instead define them as strings of Perl code operating on
\&\f(CW$_\fR:
.PP
.Vb 4
\& PathTiny\->plus_coercions(
\& Str, q{ "Path::Tiny"\->new($_) },
\& Undef, q{ "Path::Tiny"\->new("/etc/myapp/default.conf") },
\& );
.Ve
.PP
The latter will run faster, so is preferable at least for simple
coercions.
.PP
This makes the most difference when used with Moo, which supports
inlining of coercions. Moose does not inline coercions, but
providing coercions as strings still allows Type::Tiny to optimize the
coercion coderef it provides to Moose.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017\-2018 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0
Mini Shell