NAME¶
Aspect::Pointcut - API for determining which events should be hooked
DESCRIPTION¶
Aspect-Oriented Programming implementations draw much of their power from the
flexibility that can be applied to when a function call should or should not
be hooked.
Aspec::Pointcut provides a robust and powerful API for defining the rules
for when a function call should be hooked, and then applying the rules as
optimally as possible. This optimisation is particularly important for any
pure-Perl implementation, which cannot hook deeply into the underlying virtual
machine as you might with a Java or Perl XS-based implementation.
A running program can be seen as a collection of events. Events like a sub
returning from a call, or a package being used. These are called join points.
A pointcut defines a set of join points, taken from all the join points in the
program. Different pointcut classes allow you to define the set in different
ways, so you can target the exact join points you need.
Pointcuts are constructed as trees; logical operations on pointcuts with one or
two arguments (not, and, or) are themselves pointcut operators. You can
construct them explicitly using object syntax, or you can use the convenience
functions exported by Aspect and the overloaded operators "!",
"&" and "|".
METHODS¶
new¶
The "new" constructor creates new pointcut objects.
All pointcut classes define their own rules around the parameters that are
provided, but once created these pointcuts can then all be mixed together in
an arbitrary fashion.
Note: Unlike most Perl objects the default and recommended underlying datatype
for pointcut objects is an "ARRAY" reference rather than
"HASH" references. This is done because pointcut code can directly
impact the speed of function calls, and so is extremely performance sensitive.
match_all¶
my @fully_resolved_function_names = $pointcut->match_all;
The "match_all" method is the primary compile-time function called on
the pointcut model by the core Aspect library.
It will examine the list of all loaded functions and identify those which could
potentially match, and will need to have hooks installed to intercept calls to
those functions.
These functions will not necesarily all result in Aspect code being run. Some
functions may be called in all cases, but often further run-time analyis needs
to be done before we can be sure the particular function call respresents a
match.
Returns a list of fully-resolved function names (e.g.
"Module::Name::function")
match_define¶
my $should_hook = $pointcut->match_define;
At compile time, the only common factor in predicting the future state of a
function call is the name of the function itself.
The "match_define" method is called on the pointcut for each
theoretically-matchable function in the entire Perl namespace that part of an
ignored namespace, passing a single parameter of the fully-resolved function
name.
The method will determine if the function
might match, and needs to be
hooked for further checking at run-time, potentially calling
"match_define" on child objects as well.
Returns true if the function might match the pointcut, or false if the function
can never possibly match the pointcut and should never be checked at run-time.
compile_weave¶
The "compile_weave" method generates a custom function that is used to
test if a particular named function should be hooked as a potential join
point.
compile_runtime¶
The "compile_runtime" method generates a custom function that is used
to test if a particular named function should be hooked as a potential join
point.
match_contains¶
my $calls = $pointcut->match_contains('Aspect::Pointcut::Call');
The "match_contains" method provides a convenience for the validation
and optimisation systems. It is used to check for the existance of a
particular condition type anywhere within the pointcut object tree.
Returns the number of instances of a particular pointcut type within the tree.
match_always¶
my $always = $pointcut->match_contains('Aspect::Pointcut::Throwing');
The "match_always" method provides a convenience for the validation
and optimisation systems. It is used to check that a particular condition type
will be tested at least once for a matching join point, regardless of which
path the match takes through branching pointcut logic.
Returns true if an expression type is encounter at least once in all branches,
or false if there is any branch path that can be taken in which the condition
won't be encountered.
curry_runtime¶
my $optimized_pointcut = $raw_pointcut->curry_runtime;
In a production system, pointcut declarations can result in large and complex
Aspect::Pointcut object trees.
Because this tree can contain a large amount of structure that is no longer
relevant at run-time, it can end up making a long series of prohibitively
expensive cascading method or function calls before every single regular
function call.
To reduce this cost down to something more reasonable, pointcuts are run through
a currying process (see <
http://en.wikipedia.org/wiki/Currying>).
A variety of optimisations are used to simplify boolean nesting, to remove tests
that are irrelevant once the compile-time hooks have all been set up, and to
remove other tests that the currying process can determine will never need to
be tested.
The currying process will generate and return a new pointcut tree that is
independent from the original, and that can perform a match test at the
structurally minimum computational cost.
Returns a new optimised
Aspect::Pointcut object if any further testing
needs to be done at run-time for the pointcut. Returns null ("undef"
in scalar context or "()" in list context) if the pointcut can be
curried away to nothing, and no further testing needs to be done at run-time.
curry_weave¶
The "curry_weave" method is similar to the "curry_runtime"
method, except that instead of reducing the pointcut to only elements that are
relevant at run-time, it reduces the pointcut to only elements that are
relevant at weave time.
By remove purely run-time elements, the compile weave test code is made both
faster and more accurate (some complicated situations can occur when there is
a Aspect::Pointcut::Not in the tree).
AUTHORS¶
Adam Kennedy <adamk@cpan.org>
Marcel Gruenauer <marcel@cpan.org>
Ran Eilam <eilara@cpan.org>
COPYRIGHT¶
Copyright 2001 by Marcel Gruenauer
Some parts copyright 2009 - 2013 Adam Kennedy.
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.