=encoding euc-jp

=head1 名前

threads::shared - Perl extension for sharing data structures between threads

threads::shared - スレッド間でデータ構造を共有するためのPerl拡張

=head1 概要

  use threads;
  use threads::shared;

  my $var : shared;

  my($scalar, @array, %hash);
  share($scalar);
  share(@array);
  share(%hash);
  my $bar = &share([]);
  $hash{bar} = &share({});

  { lock(%hash); ...  }

  cond_wait($scalar);
  cond_broadcast(@array);
  cond_signal(%hash);

=head1 説明

By default, variables are private to each thread, and each newly created
thread gets a private copy of each existing variable.  This module allows
you to share variables across different threads (and pseudoforks on Win32).
It is used together with the threads module.

デフォルトで変数は各スレッドに対しプライベートである。新たに生成されたスレッドは、
存在している変数のプライベートなコピーを得る。このモジュールは異なるスレッド（とWin32上の擬似fork）間で変数を共有することを可能にする。threadsモジュールと一緒に使う。

=head1 EXPORT

C<share>, C<lock>, C<cond_wait>, C<cond_signal>, C<cond_broadcast>

Note that if this module is imported when C<threads> has not yet been
loaded, then these functions all become no-ops. This makes it possible
to write modules that will work in both threaded and non-threaded
environments.

まだC<threads>がロードされていない段階でこのモジュールをインポートすると、その機能は全て無効になることに注意。
これにより、スレッド・非スレッド環境の両方で動作するモジュールを書くことができる。


=head1 関数

=over 4

=item share VARIABLE

C<share> takes a value and marks it as shared. You can share a scalar,
array, hash, scalar ref, array ref or hash ref.  C<share> will return
the shared rvalue.

C<share>は値を引数に取り、それを共有化されたものとしてマークする。
スカラー、配列、ハッシュ、スカラーリファレンス、配列リファレンス、ハッシュリファレンスを共有化することができる。C<share>は共有化された右辺値(rvalue)を返す。

C<share> will traverse up references exactly I<one> level.
C<share(\$a)> is equivalent to C<share($a)>, while C<share(\\$a)> is not.

C<share>は正確にI<1>レベルリファレンスを辿る。C<share(\$a)>はC<share($a)>と等価だ。しかしC<share(\\$a)>はそうではない。

A variable can also be marked as shared at compile time by using the
C<shared> attribute: C<my $var : shared>.

C<shared>属性（ C<my $var : shared> ）を使うことで、ある変数をコンパイル時に共有化されたものとしてマークすることもできる。

If you want to share a newly created reference unfortunately you
need to use C<&share([])> and C<&share({})> syntax due to problems
with Perl's prototyping.

もし新たに生成したリファレンスを共有したい場合、残念ながら、
Perlのプロトタイプ宣言に伴う問題で、C<&share([])>とC<&share({})>
という構文を使う必要がある。

=item lock VARIABLE

C<lock> places a lock on a variable until the lock goes out of scope.
If the variable is locked by another thread, the C<lock> call will
block until it's available. C<lock> is recursive, so multiple calls
to C<lock> are safe -- the variable will remain locked until the
outermost lock on the variable goes out of scope.

C<lock>はスコープから外れるまで変数をロックする。もし他のスレッドによってその変数がロックされているなら、ロックが可能になるまでC<lock>の呼び出しはブロックする。
C<lock>は再帰的なので複数回コールしても安全である。-- 最も外側のロックがスコープから抜けるまでその変数はロックされ続ける。

If a container object, such as a hash or array, is locked, all the
elements of that container are not locked. For example, if a thread
does a C<lock @a>, any other thread doing a C<lock($a[12])> won't block.

ハッシュや配列といったコンテナオブジェクトがロックされるからといって、そこに含まれる全ての要素がロックされるわけではない。
例えば、あるスレッドがC<lock @a>するとしても、他のスレッドの行うC<lock($a[12])>はブロックされない。

C<lock> will traverse up references exactly I<one> level.
C<lock(\$a)> is equivalent to C<lock($a)>, while C<lock(\\$a)> is not.

C<lock>は正確にI<1>レベルリファレンスを辿る。C<lock(\$a)>はC<lock($a)>と等価だ。しかしC<lock(\\$a)>はそうではない。

Note that you cannot explicitly unlock a variable; you can only wait
for the lock to go out of scope. If you need more fine-grained
control, see L<Thread::Semaphore>.

明示的に変数をunlockすることはできないことに注意；ロックがスコープを抜けるのを待つしかない。もしも、よりうまい制御を望むならL<Thread::Semaphore>を見ること。

=item cond_wait VARIABLE

The C<cond_wait> function takes a B<locked> variable as a parameter,
unlocks the variable, and blocks until another thread does a
C<cond_signal> or C<cond_broadcast> for that same locked variable.
The variable that C<cond_wait> blocked on is relocked after the
C<cond_wait> is satisfied.  If there are multiple threads
C<cond_wait>ing on the same variable, all but one will reblock waiting
to reacquire the lock on the variable. (So if you're only using
C<cond_wait> for synchronisation, give up the lock as soon as
possible). The two actions of unlocking the variable and entering the
blocked wait state are atomic, The two actions of exiting from the
blocked wait state and relocking the variable are not.

C<cond_wait>関数はB<ロックされた>変数を引数に取り、その変数のロックを解除する。
そして他のスレッドがその同じロックされていた変数に向けてC<cond_signal>かC<cond_broadcast>するまで、ブロックする。
C<cond_wait>がブロックする変数は、C<cond_wait>が完了した後、再度ロックされる。
もし複数のスレッドが同じ変数に対してC<cond_wait>しているなら、一つを除いて全てのスレッドがロックを再獲得するまで待機するためにブロックに入る（だから、同期のためにC<cond_wait>を使うだけなら、可能な限り早くロックを解除すること）。
変数のロック解除と、ブロックされて待ち状態に入るという二つの動作は、アトミックである。待ち状態から抜けることと、変数への再ロックという二つの動作は、アトミックではない。

It is important to note that the variable can be notified even if
no thread C<cond_signal> or C<cond_broadcast> on the variable.
It is therefore important to check the value of the variable and
go back to waiting if the requirement is not fulfilled.

どのスレッドも変数に対しC<cond_signal>やC<cond_broadcast>をしなくても、その変数はnotifyされうるということに注意することが大切だ。
それゆえ、変数の値のチェックと、要求が満たされない場合に待ち状態に戻ることが重要である。

=item cond_signal VARIABLE

The C<cond_signal> function takes a B<locked> variable as a parameter
and unblocks one thread that's C<cond_wait>ing on that variable. If
more than one thread is blocked in a C<cond_wait> on that variable,
only one (and which one is indeterminate) will be unblocked.

C<cond_signal>関数はB<ロックされた>変数を引数に取り、その変数をC<cond_wait>している一つのスレッドのブロックを解除する。
もし一つ以上のスレッドがC<cond_wait>してブロックされているなら、ただ一つのスレッドだけがブロックを解除される（どれがなるかは不確定）。

If there are no threads blocked in a C<cond_wait> on the variable,
the signal is discarded. By always locking before signaling, you can
(with care), avoid signaling before another thread has entered cond_wait().

もしどのスレッドもその変数をC<cond_wait>していない場合、シグナルは破棄される。
常にシグナルの前にロックされるので、他のスレッドがcond_wait()に入る前にシグナルを発するのを回避することが（注意深くやれば）出来る。

C<cond_signal> will normally generate a warning if you attempt to use it
on an unlocked variable. On the rare occasions where doing this may be
sensible, you can skip the warning with

ロックされていない変数に対しC<cond_signal>を試みると、通常は警告を発する。
稀に、この警告がうるさい場合、次の方法で警告をスキップすることができる。

    { no warnings 'threads'; cond_signal($foo) }


=item cond_broadcast VARIABLE

The C<cond_broadcast> function works similarly to C<cond_signal>.
C<cond_broadcast>, though, will unblock B<all> the threads that are
blocked in a C<cond_wait> on the locked variable, rather than only one.

C<cond_broadcast>関数はC<cond_signal>とよく似た働きをする。
しかし、C<cond_broadcast>は、一つだけではなく、ロックされた変数に対してC<cond_wait>して待機中のB<全>スレッドをブロック解除する。

=back

=head1 注意

threads::shared is designed to disable itself silently if threads are
not available. If you want access to threads, you must C<use threads>
before you C<use threads::shared>.  threads will emit a warning if you
use it after threads::shared.

threadsが利用できない場合、threads::sharedは黙って利用不可になるよう設計されている。
threadsにアクセスしようとするなら、C<use threads::shared>する前にC<use threads>しなければならない。threads::sharedの後にthreadsをuseしようとすれば、警告が発せられる。

=head1 バグ

C<bless> is not supported on shared references. In the current version,
C<bless> will only bless the thread local reference and the blessing
will not propagate to the other threads. This is expected to be
implemented in a future version of Perl.

C<bless>は共有リファレンスに対してはサポートしていない。
現行のバージョンでは、C<bless>はスレッドローカルなリファレンスをblessするだけである。
blessは他のスレッドにまで伝搬しない。将来のPerlのバージョンでは実装されることが期待されている。

Does not support splice on arrays!

配列に対するspliceはサポートしていない！

Taking references to the elements of shared arrays and hashes does not
autovivify the elements, and neither does slicing a shared array/hash
over non-existent indices/keys autovivify the elements.

共有化された配列とハッシュの要素へのリファレンスをとっても、自動活性化しない。また、共有配列／ハッシュで存在しないインデックスやキーにスライスしても、その要素は自動活性化しない。

share() allows you to C<share $hashref-E<gt>{key}> without giving any error
message.  But the C<$hashref-E<gt>{key}> is B<not> shared, causing the error
"locking can only be used on shared values" to occur when you attempt to
C<lock $hasref-E<gt>{key}>.

C<share $hashref-E<gt>{key}>しても、share()はエラーメッセージを出さない。
しかし、C<$hashref-E<gt>{key}>は共有B<されない>。C<lock $hasref-E<gt>{key}>しようとすれば
"locking can only be used on shared values"（ロックは共有変数に対してのみ使用できる）というエラーが発生する。

=head1 著者

Arthur Bergman E<lt>arthur at contiller.seE<gt>

threads::shared is released under the same license as Perl

Documentation borrowed from the old Thread.pm

=head1 SEE ALSO

L<threads>, L<perlthrtut>, L<http://www.perl.com/pub/a/2002/06/11/threads.html>