=encoding euc-jp

=head1 名前

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_timedwait($scalar, time() + 30);
  cond_broadcast(@array);
  cond_signal(%hash);

  my $lockvar : shared;
  # condition var != lock var
  cond_wait($var, $lockvar);
  cond_timedwait($var, time()+30, $lockvar);

=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 エクスポート

C<share>, C<cond_wait>, C<cond_timedwait>, 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 but always as a reference.

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

=item cond_wait CONDVAR, LOCKVAR

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>を使うだけなら、可能な限り
早くロックを解除すること）。変数のロック解除と、ブロックされて待ち状態に
入るという二つの動作はアトミックである。待ち状態から抜けることと、
変数の再ロックという二つの動作は、アトミックではない。

In its second form, C<cond_wait> takes a shared, B<unlocked> variable
followed by a shared, B<locked> variable.  The second variable is
unlocked and thread execution suspended until another thread signals
the first variable.

第二の書式では、C<cond_wait>はB<ロックされていない>共有変数をとり、
その後ろにB<ロック>された共有変数がくる。この二番目の変数はロックが
解除され、そして他のスレッドが一番目の変数にシグナルを送るまで、
そのスレッドの実行は停止する。

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.  For example,
to pause until a shared counter drops to zero:

どのスレッドも、変数に対しC<cond_signal>やC<cond_broadcast>をしなくても、
その変数はnotifyされうるということに注意することが大切だ。
それゆえ、変数の値のチェック及び、要求が満たされない場合に待ち状態へ戻る
ことが重要である。例えば、共有カウンタが0になるまで停止する：

    { lock($counter); cond_wait($count) until $counter == 0; }

=item cond_timedwait VARIABLE, ABS_TIMEOUT

=item cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR

In its two-argument form, C<cond_timedwait> takes a B<locked> variable
and an absolute timeout as parameters, unlocks the variable, and blocks
until the timeout is reached or another thread signals the variable.  A
false value is returned if the timeout is reached, and a true value
otherwise.  In either case, the variable is re-locked upon return.

二つの引数をとる形式では、C<cond_timedwait>はB<ロックされた>変数と
タイムアウトの絶対時間を引数にとる。変数はロック解除され、タイムアウト
時間に達するか、他のスレッドが変数にシグナルを送るかするまでブロック
される。タイムアウトになると偽の値が返される。そうでなければ真の値が
返される。どちらの場合でも戻りの際に変数は再ロックされる。

Like C<cond_wait>, this function may take a shared, B<locked> variable
as an additional parameter; in this case the first parameter is an
B<unlocked> condition variable protected by a distinct lock variable.

C<cond_wait>同様、この関数はB<ロックされた>共有変数を追加のパラメータ
としてとれる；この場合、最初のパラメータはB<ロックされていない>条件変数
であり、これと区別されるロック変数によって守られる。

Again like C<cond_wait>, waking up and reacquiring the lock are not
atomic, and you should always check your desired condition after this
function returns.  Since the timeout is an absolute value, however, it
does not have to be recalculated with each pass:

さらにC<cond_wait>同様、覚醒とロックの再獲得はアトミックでない。
この関数が戻った後、あなたが望んだ状態になっているかどうか常にチェック
するべきだろう。しかし、タイムアウトは絶対的な値なので、パスごとに再計算
させるべきではない：

    lock($var);
    my $abs = time() + 15;
    until ($ok = desired_condition($var)) {
      last if !cond_timedwait($var, $abs);
    }
    # $okならそれを得る。そうでなければタイムアウト！

=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->{key} >> without giving any error
message.  But the C<< $hashref->{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->{key} >>.

C<< share $hashref->{key} >>しても、share()はエラーメッセージを出さない。
しかし、C<< $hashref->{key} >>は共有B<されない>。C<< lock $hasref->{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 参考

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