Document C<our $foo : shared>

Message-ID: <Pine.LNX.4.21.0105061847090.9500-100000@localhost.localdomain>

p4raw-id: //depot/perl@10014

diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index 4f3c4d7..1feb80a 100644 (file)
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2935,6 +2935,8 @@ See L<utf8> for more about Unicode.
 
 =item our EXPR
 
+=item our EXPR : ATTRIBUTES
+
 An C<our> declares the listed variables to be valid globals within
 the enclosing block, file, or C<eval>.  That is, it has the same
 scoping rules as a "my" declaration, but does not create a local
@@ -2973,6 +2975,28 @@ package, Perl will emit warnings if you have asked for them.
 
     our $bar;          # emits warning
 
+An C<our> declaration may also have a list of attributes associated
+with it.  B<WARNING>: This is an experimental feature that may be
+changed or removed in future releases of Perl.  It should not be
+relied upon.
+
+The only currently recognized attribute is C<shared> which indicates
+that a single copy of the global is to be used by all interpreters
+should the program happen to be running in a multi-interpreter
+environment. (The default behaviour would be for each interpreter to
+have its own copy of the global.)  In such an environment, this
+attribute also has the effect of making the global readonly.
+Examples:
+
+    our @EXPORT : shared = qw(foo);
+    our %EXPORT_TAGS : shared = (bar => [qw(aa bb cc)]);
+    our $VERSION : shared = "1.00";
+
+Multi-interpreter environments can come to being either through the
+fork() emulation on Windows platforms, or by embedding perl in a
+multi-threaded application.  The C<shared> attribute does nothing in
+all other environments.
+
 =item pack TEMPLATE,LIST
 
 Takes a LIST of values and converts it into a string using the rules