Make op_info thread safe

[perl/modules/Variable-Magic.git] / README

diff --git a/README b/README
index d5004fc0fd7ac68598b453f4a6961dca6b4b84dd..4b7401275cd6dc507c5b39bcf0b3f4493ba3b805 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION
     Variable::Magic - Associate user-defined magic to variables from Perl.
 
 VERSION

-    Version 0.27
+    Version 0.30

 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;
 
 SYNOPSIS
         use Variable::Magic qw/wizard cast dispell/;


@@ -204,21 +204,31 @@ CONSTANTS
     True iff this module could have been built with thread-safety features
     enabled.
 
     True iff this module could have been built with thread-safety features
     enabled.
 

+  "VMG_OP_INFO_NAME"
+    Value to pass with "op_info" to get the current op name in the magic
+    callbacks.
+
+  "VMG_OP_INFO_OBJECT"
+    Value to pass with "op_info" to get a "B::OP" object representing the
+    current op in the magic callbacks.
+

 FUNCTIONS
   "wizard"
 FUNCTIONS
   "wizard"

-        wizard sig    => ...,
-               data   => sub { ... },
-               get    => sub { my ($ref, $data) = @_; ... },
-               set    => sub { my ($ref, $data) = @_; ... },
-               len    => sub { my ($ref, $data, $len) = @_; ... ; return $newlen; },
-               clear  => sub { my ($ref, $data) = @_; ... },
-               free   => sub { my ($ref, $data) = @_, ... },
-               copy   => sub { my ($ref, $data, $key, $elt) = @_; ... },
-               local  => sub { my ($ref, $data) = @_; ... },
-               fetch  => sub { my ($ref, $data, $key) = @_; ... },
-               store  => sub { my ($ref, $data, $key) = @_; ... },
-               exists => sub { my ($ref, $data, $key) = @_; ... },
-               delete => sub { my ($ref, $data, $key) = @_; ... }
+        wizard sig      => ...,
+               data     => sub { ... },
+               get      => sub { my ($ref, $data [, $op]) = @_; ... },
+               set      => sub { my ($ref, $data [, $op]) = @_; ... },
+               len      => sub { my ($ref, $data, $len [, $op]) = @_; ... ; return $newlen; },
+               clear    => sub { my ($ref, $data [, $op]) = @_; ... },
+               free     => sub { my ($ref, $data [, $op]) = @_, ... },
+               copy     => sub { my ($ref, $data, $key, $elt [, $op]) = @_; ... },
+               local    => sub { my ($ref, $data [, $op]) = @_; ... },
+               fetch    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               store    => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               exists   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               delete   => sub { my ($ref, $data, $key [, $op]) = @_; ... },
+               copy_key => $bool,
+               op_info  => [ 0 | VMG_OP_INFO_NAME | VMG_OP_INFO_OBJECT ]

 
     This function creates a 'wizard', an opaque type that holds the magic
     information. It takes a list of keys / values as argument, whose keys
 
     This function creates a 'wizard', an opaque type that holds the magic
     information. It takes a list of keys / values as argument, whose keys


@@ -241,17 +251,44 @@ FUNCTIONS
     *   "get", "set", "len", "clear", "free", "copy", "local", "fetch",
         "store", "exists" and "delete"
 
     *   "get", "set", "len", "clear", "free", "copy", "local", "fetch",
         "store", "exists" and "delete"
 

-        Code references to corresponding magic callbacks. You don't have to
-        specify all of them : the magic associated with undefined entries
+        Code references to the corresponding magic callbacks. You don't have
+        to specify all of them : the magic associated with undefined entries

         simply won't be hooked. In those callbacks, $_[0] is always a
         reference to the magic object and $_[1] is always the private data
         simply won't be hooked. In those callbacks, $_[0] is always a
         reference to the magic object and $_[1] is always the private data

-        (or "undef" when no private data constructor was supplied). In the
-        special case of "len" magic and when the variable is an array, $_[2]
-        contains its normal length. $_[2] is the current key in "copy",
-        "fetch", "store", "exists" and "delete" callbacks, although for
-        "copy" it may just be a copy of the actual key so it's useless to
-        (for example) cast magic on it. "copy" magic also receives the
-        current element (i.e. the value) in $_[3].
+        (or "undef" when no private data constructor was supplied).
+
+        Moreover, when you pass "op_info => $num" to "wizard", the last
+        element of @_ will be the current op name if "$num ==
+        VMG_OP_INFO_NAME" and a "B::OP" object representing the current op
+        if "$num == VMG_OP_INFO_OBJECT". Both have a performance hit, but
+        just getting the name is lighter than getting the op object.
+
+        Other arguments are specific to the magic hooked :
+
+        *       "len"
+
+                When the variable is an array or a scalar, $_[2] contains
+                the non-magical length. The callback can return the new
+                scalar or array length to use, or "undef" to default to the
+                normal length.
+
+        *       "copy"
+
+                $_[2] is a either a copy or an alias of the current key,
+                which means that it is useless to try to change or cast
+                magic on it. $_[3] is an alias to the current element (i.e.
+                the value).
+
+        *       "fetch", "store", "exists" and "delete"
+
+                $_[2] is an alias to the current key. Nothing prevents you
+                from changing it, but be aware that there lurk dangerous
+                side effects. For example, it may righteously be readonly if
+                the key was a bareword. You can get a copy instead by
+                passing "copy_key => 1" to "wizard", which allows you to
+                safely assign to $_[2] in order to e.g. redirect the action
+                to another key. This however has a little performance
+                drawback because of the copy.

 
         All the callbacks are expected to return an integer, which is passed
         straight to the perl magic API. However, only the return value of
 
         All the callbacks are expected to return an integer, which is passed
         straight to the perl magic API. However, only the return value of


@@ -294,6 +331,18 @@ FUNCTIONS
         my $x;
         die 'error' unless cast $x, $wiz;
 
         my $x;
         die 'error' unless cast $x, $wiz;
 

+    The "var" argument can be an array or hash value. Magic for those
+    behaves like for any other scalar, except that it is dispelled when the
+    entry is deleted from the container. For example, if you want to call
+    "POSIX::tzset" each time the 'TZ' environment variable is changed in
+    %ENV, you can use :
+
+        use POSIX;
+        cast $ENV{TZ}, wizard set => sub { POSIX::tzset(); () };
+
+    If you want to overcome the possible deletion of the 'TZ' entry, you
+    have no choice but to rely on "store" uvar magic.
+

   "getdata"
         getdata [$@%&*]var, [$wiz|$sig]
 
   "getdata"
         getdata [$@%&*]var, [$wiz|$sig]
 


@@ -335,10 +384,8 @@ CAVEATS
     this destructor won't be called because the wizard will be destroyed
     first.
 
     this destructor won't be called because the wizard will be destroyed
     first.
 

-    Using "get" and "clear" magics on hashes may cause segfaults.
-

 DEPENDENCIES
 DEPENDENCIES

-    perl 5.7.3.
+    perl 5.8.

 
     Carp (standard since perl 5), XSLoader (standard since perl 5.006).
 
 
     Carp (standard since perl 5), XSLoader (standard since perl 5.006).