Make sure we don't take the OP_REFCNT mutex twice on perl 5.9.2 and below

[perl/modules/indirect.git] / README

diff --git a/README b/README
index ab4fa5e204652fa8988e61722ca8dc0cbe088095..f2153cfdb5f0557d0530f6686f11d1f35f9c9ffa 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     indirect - Lexically warn about using the indirect method call syntax.
 
 VERSION
     indirect - Lexically warn about using the indirect method call syntax.
 
 VERSION

-    Version 0.26
+    Version 0.34

 
 SYNOPSIS
     In a script :
 
 SYNOPSIS
     In a script :


@@ -41,10 +41,9 @@ DESCRIPTION
     The indirect syntax is now considered harmful, since its parsing has
     many quirks and its use is error prone : when the subroutine "foo" has
     not been declared in the current package, "foo $x" actually compiles to
     The indirect syntax is now considered harmful, since its parsing has
     many quirks and its use is error prone : when the subroutine "foo" has
     not been declared in the current package, "foo $x" actually compiles to

-    "$x->foo", and "foo { key => 1 }" to "'key'->foo(1)". In
-    <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>,
-    Matt S. Trout gives an example of an undesirable indirect method call on
-    a block that can cause a particularly bewildering error.
+    "$x->foo", and "foo { key => 1 }" to "'key'->foo(1)". Please refer to
+    the "REFERENCES" section for a more complete list of reasons for
+    avoiding this construct.

 
     This pragma currently does not warn for core functions ("print", "say",
     "exec" or "system"). This may change in the future, or may be added as
 
     This pragma currently does not warn for core functions ("print", "say",
     "exec" or "system"). This may change in the future, or may be added as


@@ -54,7 +53,14 @@ DESCRIPTION
     This module is not a source filter.
 
 METHODS
     This module is not a source filter.
 
 METHODS

-  "unimport [ 'global', hook => $hook | 'fatal' ]"
+  "unimport"
+        no indirect;
+        no indirect 'fatal';
+        no indirect hook => sub { my ($obj, $name, $file, $line) = @_; ... };
+        no indirect 'global';
+        no indirect 'global, 'fatal';
+        no indirect 'global', hook => sub { ... };
+

     Magically called when "no indirect @opts" is encountered. Turns the
     module on. The policy to apply depends on what is first found in @opts :
 
     Magically called when "no indirect @opts" is encountered. Turns the
     module on. The policy to apply depends on what is first found in @opts :
 


@@ -101,6 +107,8 @@ METHODS
             }
 
   "import"
             }
 
   "import"

+        use indirect;
+

     Magically called at each "use indirect". Turns the module off.
 
     As explained in "unimport"'s description, an "use indirect" statement
     Magically called at each "use indirect". Turns the module off.
 
     As explained in "unimport"'s description, an "use indirect" statement


@@ -108,7 +116,9 @@ METHODS
     indirect 'global', ..." (if there's one).
 
 FUNCTIONS
     indirect 'global', ..." (if there's one).
 
 FUNCTIONS

-  "msg $object, $method, $file, $line"
+  "msg"
+        my $msg = msg($object, $method, $file, $line);
+

     Returns the default error message that "indirect" generates when an
     indirect method call is reported.
 
     Returns the default error message that "indirect" generates when an
     indirect method call is reported.
 


@@ -159,16 +169,38 @@ CAVEATS
     is due to a shortcoming in the way perl handles the hints hash, which is
     addressed in perl 5.10.
 
     is due to a shortcoming in the way perl handles the hints hash, which is
     addressed in perl 5.10.
 

+    Indirect constructs that appear in code "eval"'d during the global
+    destruction phase of a spawned thread or pseudo-fork (the processes used
+    internally for the "fork" emulation on Windows) are not reported.
+

     The search for indirect method calls happens before constant folding.
     Hence "my $x = new Class if 0" will be caught.
 
     The search for indirect method calls happens before constant folding.
     Hence "my $x = new Class if 0" will be caught.
 

+REFERENCES
+    Numerous articles have been written about the quirks of the indirect
+    object construct :
+
+    *   <http://markmail.org/message/o7d5sxnydya7bwvv> : Far More Than
+        Everything You've Ever Wanted to Know about the Indirect Object
+        syntax, Tom Christiansen, 1998-01-28.
+
+        This historical post to the "perl5-porters" mailing list raised
+        awareness about the perils of this syntax.
+
+    *   <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fat
+        al> : Indirect but still fatal, Matt S. Trout, 2009-07-29.
+
+        In this blog post, the author gives an example of an undesirable
+        indirect method call on a block that causes a particularly
+        bewildering error.
+

 DEPENDENCIES
     perl 5.8.1.
 
     A C compiler. This module may happen to build with a C++ compiler as
     well, but don't rely on it, as no guarantee is made in this regard.
 
 DEPENDENCIES
     perl 5.8.1.
 
     A C compiler. This module may happen to build with a C++ compiler as
     well, but don't rely on it, as no guarantee is made in this regard.
 

-    Carp (standard since perl 5), XSLoader (since perl 5.006).
+    Carp (standard since perl 5), XSLoader (since perl 5.6.0).

 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.


@@ -197,7 +229,8 @@ ACKNOWLEDGEMENTS
     reporting issues.
 
 COPYRIGHT & LICENSE
     reporting issues.
 
 COPYRIGHT & LICENSE

-    Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
+    Copyright 2008,2009,2010,2011,2012,2013,2014,2015 Vincent Pit, all
+    rights reserved.

 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.