home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / lib / perl / 5.10.0 / threads / shared.pm
Encoding:
Perl POD Document  |  2009-06-26  |  12.2 KB  |  395 lines
  1. package threads::shared;
  2.  
  3. use 5.008;
  4.  
  5. use strict;
  6. use warnings;
  7.  
  8. our $VERSION = '1.14';
  9. my $XS_VERSION = $VERSION;
  10. $VERSION = eval $VERSION;
  11.  
  12. # Declare that we have been loaded
  13. $threads::shared::threads_shared = 1;
  14.  
  15. # Load the XS code, if applicable
  16. if ($threads::threads) {
  17.     require XSLoader;
  18.     XSLoader::load('threads::shared', $XS_VERSION);
  19.  
  20.     *is_shared = \&_id;
  21.  
  22. } else {
  23.     # String eval is generally evil, but we don't want these subs to
  24.     # exist at all if 'threads' is not loaded successfully.
  25.     # Vivifying them conditionally this way saves on average about 4K
  26.     # of memory per thread.
  27.     eval <<'_MARKER_';
  28.         sub share          (\[$@%])         { return $_[0] }
  29.         sub is_shared      (\[$@%])         { undef }
  30.         sub cond_wait      (\[$@%];\[$@%])  { undef }
  31.         sub cond_timedwait (\[$@%]$;\[$@%]) { undef }
  32.         sub cond_signal    (\[$@%])         { undef }
  33.         sub cond_broadcast (\[$@%])         { undef }
  34. _MARKER_
  35. }
  36.  
  37.  
  38. ### Export ###
  39.  
  40. sub import
  41. {
  42.     # Exported subroutines
  43.     my @EXPORT = qw(share is_shared cond_wait cond_timedwait
  44.                     cond_signal cond_broadcast);
  45.     if ($threads::threads) {
  46.         push(@EXPORT, 'bless');
  47.     }
  48.  
  49.     # Export subroutine names
  50.     my $caller = caller();
  51.     foreach my $sym (@EXPORT) {
  52.         no strict 'refs';
  53.         *{$caller.'::'.$sym} = \&{$sym};
  54.     }
  55. }
  56.  
  57.  
  58. ### Methods, etc. ###
  59.  
  60. sub threads::shared::tie::SPLICE
  61. {
  62.     require Carp;
  63.     Carp::croak('Splice not implemented for shared arrays');
  64. }
  65.  
  66. 1;
  67.  
  68. __END__
  69.  
  70. =head1 NAME
  71.  
  72. threads::shared - Perl extension for sharing data structures between threads
  73.  
  74. =head1 VERSION
  75.  
  76. This document describes threads::shared version 1.14
  77.  
  78. =head1 SYNOPSIS
  79.  
  80.   use threads;
  81.   use threads::shared;
  82.  
  83.   my $var :shared;
  84.   $var = $scalar_value;
  85.   $var = $shared_ref_value;
  86.   $var = share($simple_unshared_ref_value);
  87.  
  88.   my ($scalar, @array, %hash);
  89.   share($scalar);
  90.   share(@array);
  91.   share(%hash);
  92.   my $bar = &share([]);
  93.   $hash{bar} = &share({});
  94.  
  95.   { lock(%hash); ...  }
  96.  
  97.   cond_wait($scalar);
  98.   cond_timedwait($scalar, time() + 30);
  99.   cond_broadcast(@array);
  100.   cond_signal(%hash);
  101.  
  102.   my $lockvar :shared;
  103.   # condition var != lock var
  104.   cond_wait($var, $lockvar);
  105.   cond_timedwait($var, time()+30, $lockvar);
  106.  
  107. =head1 DESCRIPTION
  108.  
  109. By default, variables are private to each thread, and each newly created
  110. thread gets a private copy of each existing variable.  This module allows you
  111. to share variables across different threads (and pseudo-forks on Win32).  It is
  112. used together with the L<threads> module.
  113.  
  114. =head1 EXPORT
  115.  
  116. C<share>, C<cond_wait>, C<cond_timedwait>, C<cond_signal>, C<cond_broadcast>,
  117. C<is_shared>
  118.  
  119. Note that if this module is imported when L<threads> has not yet been loaded,
  120. then these functions all become no-ops.  This makes it possible to write
  121. modules that will work in both threaded and non-threaded environments.
  122.  
  123. =head1 FUNCTIONS
  124.  
  125. =over 4
  126.  
  127. =item share VARIABLE
  128.  
  129. C<share> takes a value and marks it as shared. You can share a scalar, array,
  130. hash, scalar ref, array ref, or hash ref.  C<share> will return the shared
  131. rvalue, but always as a reference.
  132.  
  133. A variable can also be marked as shared at compile time by using the
  134. C<:shared> attribute: C<my $var :shared;>.
  135.  
  136. Due to problems with Perl's prototyping, if you want to share a newly created
  137. reference, you need to use the C<&share([])> and C<&share({})> syntax.
  138.  
  139. The only values that can be assigned to a shared scalar are other scalar
  140. values, or shared refs:
  141.  
  142.   my $var :shared;
  143.   $var = 1;              # ok
  144.   $var = [];             # error
  145.   $var = &share([]);     # ok
  146.  
  147. C<share> will traverse up references exactly I<one> level.  C<share(\$a)> is
  148. equivalent to C<share($a)>, while C<share(\\$a)> is not.  This means that you
  149. must create nested shared data structures by first creating individual shared
  150. leaf nodes, and then adding them to a shared hash or array.
  151.  
  152.   my %hash :shared;
  153.   $hash{'meaning'} = &share([]);
  154.   $hash{'meaning'}[0] = &share({});
  155.   $hash{'meaning'}[0]{'life'} = 42;
  156.  
  157. =item is_shared VARIABLE
  158.  
  159. C<is_shared> checks if the specified variable is shared or not.  If shared,
  160. returns the variable's internal ID (similar to
  161. L<refaddr()|Scalar::Util/"refaddr EXPR">).  Otherwise, returns C<undef>.
  162.  
  163.   if (is_shared($var)) {
  164.       print("\$var is shared\n");
  165.   } else {
  166.       print("\$var is not shared\n");
  167.   }
  168.  
  169. =item lock VARIABLE
  170.  
  171. C<lock> places a lock on a variable until the lock goes out of scope.  If the
  172. variable is locked by another thread, the C<lock> call will block until it's
  173. available.  Multiple calls to C<lock> by the same thread from within
  174. dynamically nested scopes are safe -- the variable will remain locked until
  175. the outermost lock on the variable goes out of scope.
  176.  
  177. Locking a container object, such as a hash or array, doesn't lock the elements
  178. of that container. For example, if a thread does a C<lock(@a)>, any other
  179. thread doing a C<lock($a[12])> won't block.
  180.  
  181. C<lock()> follows references exactly I<one> level.  C<lock(\$a)> is equivalent
  182. to C<lock($a)>, while C<lock(\\$a)> is not.
  183.  
  184. Note that you cannot explicitly unlock a variable; you can only wait for the
  185. lock to go out of scope.  This is most easily accomplished by locking the
  186. variable inside a block.
  187.  
  188.   my $var :shared;
  189.   {
  190.       lock($var);
  191.       # $var is locked from here to the end of the block
  192.       ...
  193.   }
  194.   # $var is now unlocked
  195.  
  196. If you need more fine-grained control over shared variable access, see
  197. L<Thread::Semaphore>.
  198.  
  199. =item cond_wait VARIABLE
  200.  
  201. =item cond_wait CONDVAR, LOCKVAR
  202.  
  203. The C<cond_wait> function takes a B<locked> variable as a parameter, unlocks
  204. the variable, and blocks until another thread does a C<cond_signal> or
  205. C<cond_broadcast> for that same locked variable.  The variable that
  206. C<cond_wait> blocked on is relocked after the C<cond_wait> is satisfied.  If
  207. there are multiple threads C<cond_wait>ing on the same variable, all but one
  208. will re-block waiting to reacquire the lock on the variable. (So if you're only
  209. using C<cond_wait> for synchronisation, give up the lock as soon as possible).
  210. The two actions of unlocking the variable and entering the blocked wait state
  211. are atomic, the two actions of exiting from the blocked wait state and
  212. re-locking the variable are not.
  213.  
  214. In its second form, C<cond_wait> takes a shared, B<unlocked> variable followed
  215. by a shared, B<locked> variable.  The second variable is unlocked and thread
  216. execution suspended until another thread signals the first variable.
  217.  
  218. It is important to note that the variable can be notified even if no thread
  219. C<cond_signal> or C<cond_broadcast> on the variable.  It is therefore
  220. important to check the value of the variable and go back to waiting if the
  221. requirement is not fulfilled.  For example, to pause until a shared counter
  222. drops to zero:
  223.  
  224.   { lock($counter); cond_wait($count) until $counter == 0; }
  225.  
  226. =item cond_timedwait VARIABLE, ABS_TIMEOUT
  227.  
  228. =item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR
  229.  
  230. In its two-argument form, C<cond_timedwait> takes a B<locked> variable and an
  231. absolute timeout as parameters, unlocks the variable, and blocks until the
  232. timeout is reached or another thread signals the variable.  A false value is
  233. returned if the timeout is reached, and a true value otherwise.  In either
  234. case, the variable is re-locked upon return.
  235.  
  236. Like C<cond_wait>, this function may take a shared, B<locked> variable as an
  237. additional parameter; in this case the first parameter is an B<unlocked>
  238. condition variable protected by a distinct lock variable.
  239.  
  240. Again like C<cond_wait>, waking up and reacquiring the lock are not atomic,
  241. and you should always check your desired condition after this function
  242. returns.  Since the timeout is an absolute value, however, it does not have to
  243. be recalculated with each pass:
  244.  
  245.   lock($var);
  246.   my $abs = time() + 15;
  247.   until ($ok = desired_condition($var)) {
  248.       last if !cond_timedwait($var, $abs);
  249.   }
  250.   # we got it if $ok, otherwise we timed out!
  251.  
  252. =item cond_signal VARIABLE
  253.  
  254. The C<cond_signal> function takes a B<locked> variable as a parameter and
  255. unblocks one thread that's C<cond_wait>ing on that variable. If more than one
  256. thread is blocked in a C<cond_wait> on that variable, only one (and which one
  257. is indeterminate) will be unblocked.
  258.  
  259. If there are no threads blocked in a C<cond_wait> on the variable, the signal
  260. is discarded. By always locking before signaling, you can (with care), avoid
  261. signaling before another thread has entered cond_wait().
  262.  
  263. C<cond_signal> will normally generate a warning if you attempt to use it on an
  264. unlocked variable. On the rare occasions where doing this may be sensible, you
  265. can suppress the warning with:
  266.  
  267.   { no warnings 'threads'; cond_signal($foo); }
  268.  
  269. =item cond_broadcast VARIABLE
  270.  
  271. The C<cond_broadcast> function works similarly to C<cond_signal>.
  272. C<cond_broadcast>, though, will unblock B<all> the threads that are blocked in
  273. a C<cond_wait> on the locked variable, rather than only one.
  274.  
  275. =back
  276.  
  277. =head1 OBJECTS
  278.  
  279. L<threads::shared> exports a version of L<bless()|perlfunc/"bless REF"> that
  280. works on shared objects such that I<blessings> propagate across threads.
  281.  
  282.   # Create a shared 'foo' object
  283.   my $foo;
  284.   share($foo);
  285.   $foo = &share({});
  286.   bless($foo, 'foo');
  287.  
  288.   # Create a shared 'bar' object
  289.   my $bar;
  290.   share($bar);
  291.   $bar = &share({});
  292.   bless($bar, 'bar');
  293.  
  294.   # Put 'bar' inside 'foo'
  295.   $foo->{'bar'} = $bar;
  296.  
  297.   # Rebless the objects via a thread
  298.   threads->create(sub {
  299.       # Rebless the outer object
  300.       bless($foo, 'yin');
  301.  
  302.       # Cannot directly rebless the inner object
  303.       #bless($foo->{'bar'}, 'yang');
  304.  
  305.       # Retrieve and rebless the inner object
  306.       my $obj = $foo->{'bar'};
  307.       bless($obj, 'yang');
  308.       $foo->{'bar'} = $obj;
  309.  
  310.   })->join();
  311.  
  312.   print(ref($foo),          "\n");    # Prints 'yin'
  313.   print(ref($foo->{'bar'}), "\n");    # Prints 'yang'
  314.   print(ref($bar),          "\n");    # Also prints 'yang'
  315.  
  316. =head1 NOTES
  317.  
  318. threads::shared is designed to disable itself silently if threads are not
  319. available. If you want access to threads, you must C<use threads> before you
  320. C<use threads::shared>.  L<threads> will emit a warning if you use it after
  321. L<threads::shared>.
  322.  
  323. =head1 BUGS AND LIMITATIONS
  324.  
  325. When C<share> is used on arrays, hashes, array refs or hash refs, any data
  326. they contain will be lost.
  327.  
  328.   my @arr = qw(foo bar baz);
  329.   share(@arr);
  330.   # @arr is now empty (i.e., == ());
  331.  
  332.   # Create a 'foo' object
  333.   my $foo = { 'data' => 99 };
  334.   bless($foo, 'foo');
  335.  
  336.   # Share the object
  337.   share($foo);        # Contents are now wiped out
  338.   print("ERROR: \$foo is empty\n")
  339.       if (! exists($foo->{'data'}));
  340.  
  341. Therefore, populate such variables B<after> declaring them as shared.  (Scalar
  342. and scalar refs are not affected by this problem.)
  343.  
  344. It is often not wise to share an object unless the class itself has been
  345. written to support sharing.  For example, an object's destructor may get
  346. called multiple times, once for each thread's scope exit.  Another danger is
  347. that the contents of hash-based objects will be lost due to the above
  348. mentioned limitation.  See F<examples/class.pl> (in the CPAN distribution of
  349. this module) for how to create a class that supports object sharing.
  350.  
  351. Does not support C<splice> on arrays!
  352.  
  353. Taking references to the elements of shared arrays and hashes does not
  354. autovivify the elements, and neither does slicing a shared array/hash over
  355. non-existent indices/keys autovivify the elements.
  356.  
  357. C<share()> allows you to C<< share($hashref->{key}) >> without giving any
  358. error message.  But the C<< $hashref->{key} >> is B<not> shared, causing the
  359. error "locking can only be used on shared values" to occur when you attempt to
  360. C<< lock($hasref->{key}) >>.
  361.  
  362. View existing bug reports at, and submit any new bugs, problems, patches, etc.
  363. to: L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=threads-shared>
  364.  
  365. =head1 SEE ALSO
  366.  
  367. L<threads::shared> Discussion Forum on CPAN:
  368. L<http://www.cpanforum.com/dist/threads-shared>
  369.  
  370. Annotated POD for L<threads::shared>:
  371. L<http://annocpan.org/~JDHEDDEN/threads-shared-1.14/shared.pm>
  372.  
  373. Source repository:
  374. L<http://code.google.com/p/threads-shared/>
  375.  
  376. L<threads>, L<perlthrtut>
  377.  
  378. L<http://www.perl.com/pub/a/2002/06/11/threads.html> and
  379. L<http://www.perl.com/pub/a/2002/09/04/threads.html>
  380.  
  381. Perl threads mailing list:
  382. L<http://lists.cpan.org/showlist.cgi?name=iThreads>
  383.  
  384. =head1 AUTHOR
  385.  
  386. Artur Bergman E<lt>sky AT crucially DOT netE<gt>
  387.  
  388. threads::shared is released under the same license as Perl.
  389.  
  390. Documentation borrowed from the old Thread.pm.
  391.  
  392. CPAN version produced by Jerry D. Hedden E<lt>jdhedden AT cpan DOT orgE<gt>.
  393.  
  394. =cut
  395.