名前¶

threads::shared - スレッド間でデータ構造を共有するための Perl エクステンション

VERSION¶

このドキュメントは threads::shared バージョン 1.29 を記述しています。

概要¶

  use threads;
  use threads::shared;

  my $var :shared;
  my %hsh :shared;
  my @ary :shared;

  my ($scalar, @array, %hash);
  share($scalar);
  share(@array);
  share(%hash);

  $var = $scalar_value;
  $var = $shared_ref_value;
  $var = shared_clone($non_shared_ref_value);
  $var = shared_clone({'foo' => [qw/foo bar baz/]});

  $hsh{'foo'} = $scalar_value;
  $hsh{'bar'} = $shared_ref_value;
  $hsh{'baz'} = shared_clone($non_shared_ref_value);
  $hsh{'quz'} = shared_clone([1..3]);

  $ary[0] = $scalar_value;
  $ary[1] = $shared_ref_value;
  $ary[2] = shared_clone($non_shared_ref_value);
  $ary[3] = shared_clone([ {}, [] ]);

  { 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);

説明¶

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

このモジュールは以下のデータ型の共有にのみ対応しています: スカラと スカラリファレンス、配列と配列リファレンス、ハッシュとハッシュリファレンス。

エクスポート¶

いかの関数がこのモジュールによってエクスポートされます: share, shared_clone, is_shared, cond_wait, cond_timedwait, cond_signal, cond_broadcast

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

関数¶

share VARIABLE

share takes a variable and marks it as shared:

share は値を引数に取り、それを共有化されたものとしてマークします:

  my ($scalar, @array, %hash);
  share($scalar);
  share(@array);
  share(%hash);

share will return the shared rvalue, but always as a reference.

share は共有された右辺値を返しますが、常にリファレンスとして返します。

Variables can also be marked as shared at compile time by using the :shared attribute:

:shared 属性を使うことで、ある変数をコンパイル時に共有化されたものとして マークすることもできます:

  my ($var, %hash, @array) :shared;

Shared variables can only store scalars, refs of shared variables, or refs of shared data (discussed in next section):

共有変数はスカラ、共有変数のリファレンス、共有されたデータの リファレンスのみを保管できます (次の節で議論します):

  my ($var, %hash, @array) :shared;
  my $bork;

  # Storing scalars
  $var = 1;
  $hash{'foo'} = 'bar';
  $array[0] = 1.5;

  # Storing shared refs
  $var = \%hash;
  $hash{'ary'} = \@array;
  $array[1] = \$var;

  # The following are errors:
  #   $var = \$bork;                    # ref of non-shared variable
  #   $hash{'bork'} = [];               # non-shared array ref
  #   push(@array, { 'x' => 1 });       # non-shared hash ref

shared_clone REF

shared_clone takes a reference, and returns a shared version of its argument, performing a deep copy on any non-shared elements. Any shared elements in the argument are used as is (i.e., they are not cloned).

shared_clone はリファレンスを取って、非共有要素のディープコピーを することによって、その引数の共有バージョンを返します。 引数の中の共有要素はそのまま使われます (つまりクローンされません)。

  my $cpy = shared_clone({'foo' => [qw/foo bar baz/]});

Object status (i.e., the class an object is blessed into) is also cloned.

オブジェクト状態 (つまりオブジェクトが bless されているクラス) も クローンされます。

  my $obj = {'foo' => [qw/foo bar baz/]};
  bless($obj, 'Foo');
  my $cpy = shared_clone($obj);
  print(ref($cpy), "\n");         # Outputs 'Foo'

For cloning empty array or hash refs, the following may also be used:

空配列やハッシュリファレンスのクローンには、以下のものも使えます:

  $var = &share([]);   # Same as $var = shared_clone([]);
  $var = &share({});   # Same as $var = shared_clone({});

is_shared VARIABLE

is_shared checks if the specified variable is shared or not. If shared, returns the variable's internal ID (similar to refaddr()). Otherwise, returns undef.

is_shared は、指定された変数が共有されているかどうかをチェックします。 共有されていれば、(refaddr() と同様に) 変数の 内部 ID を返します。 そうでなければ、undef を返します。

  if (is_shared($var)) {
      print("\$var is shared\n");
  } else {
      print("\$var is not shared\n");
  }

When used on an element of an array or hash, is_shared checks if the specified element belongs to a shared array or hash. (It does not check the contents of that element.)

配列やハッシュの要素に使われた場合、is_shared は指定された要素が 共有配列またはハッシュに従っているかどうかをチェックします。 (要素の中身はチェックしません。)

  my %hash :shared;
  if (is_shared(%hash)) {
      print("\%hash is shared\n");
  }

  $hash{'elem'} = 1;
  if (is_shared($hash{'elem'})) {
      print("\$hash{'elem'} is in a shared hash\n");
  }

lock VARIABLE

lock places a advisory lock on a variable until the lock goes out of scope. If the variable is locked by another thread, the lock call will block until it's available. Multiple calls to lock by the same thread from within dynamically nested scopes are safe -- the variable will remain locked until the outermost lock on the variable goes out of scope.

lock はスコープから外れるまで変数を 助言 ロックします。 もし他のスレッドによってその変数がロックされているなら、ロックが 可能になるまで lock の呼び出しはブロックされます。 動的にネストしたスコープの中から同じスレッドによって複数回 lock を 呼び出しても安全です -- 最も外側のロックがスコープから抜けるまでその変数は ロックされ続けます。

lock follows references exactly one level:

lock はリファレンスを正確に 1 レベル辿ります:

  my %hash :shared;
  my $ref = \%hash;
  lock($ref);           # This is equivalent to lock(%hash)

Note that you cannot explicitly unlock a variable; you can only wait for the lock to go out of scope. This is most easily accomplished by locking the variable inside a block.

明示的に変数を unlock することはできないことに注意してください; ロックがスコープを抜けるのを待つしかありません。 これはブロックの内側で変数をロックすることで最も簡単に達成できます。

  my $var :shared;
  {
      lock($var);
      # $var is locked from here to the end of the block
      ...
  }
  # $var is now unlocked

As locks are advisory, they do not prevent data access or modification by another thread that does not itself attempt to obtain a lock on the variable.

ロックは助言なので、自分自身で変数のロックを得ようとしない他のスレッドによる データアクセスや変更を防げません。

You cannot lock the individual elements of a container variable:

コンテナ変数の個々の要素のロックはできません:

  my %hash :shared;
  $hash{'foo'} = 'bar';
  #lock($hash{'foo'});          # Error
  lock(%hash);                  # Works

If you need more fine-grained control over shared variable access, see Thread::Semaphore.

もし共有変数へのアクセスについてより精度の高い制御を望むなら、 Thread::Semaphore を参照してください。

cond_wait VARIABLE

cond_wait CONDVAR, LOCKVAR

The cond_wait function takes a locked variable as a parameter, unlocks the variable, and blocks until another thread does a cond_signal or cond_broadcast for that same locked variable. The variable that cond_wait blocked on is relocked after the cond_wait is satisfied. If there are multiple threads cond_waiting on the same variable, all but one will re-block waiting to reacquire the lock on the variable. (So if you're only using 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 re-locking the variable are not.

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

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

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

It is important to note that the variable can be notified even if no thread cond_signal or 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:

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

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

cond_timedwait VARIABLE, ABS_TIMEOUT

cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR

In its two-argument form, cond_timedwait takes a 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.

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

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

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

Again like 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:

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

  lock($var);
  my $abs = time() + 15;
  until ($ok = desired_condition($var)) {
      last if !cond_timedwait($var, $abs);
  }
  # we got it if $ok, otherwise we timed out!

cond_signal VARIABLE

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

cond_signal 関数は ロックされた 変数を引数にとり、その変数に対して cond_wait している一つのスレッドのブロックを解除します。 もし一つ以上のスレッドが cond_wait してブロックされているなら、ただ一つの スレッドだけがブロックを解除されます (そしてどの一つかは不確定です)。

If there are no threads blocked in a 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().

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

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 suppress the warning with:

ロックされていない変数に対し cond_signal を試みると、通常は警告を 発します。 稀に起こるこの警告がうるさい場合、次の方法で警告を抑制することができます:

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

cond_broadcast VARIABLE

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

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

OBJECTS¶

threads::shared bless がスレッドをまたいで伝搬するような 共有オブジェクトで動作するバージョンの bless() を エクスポートします。

  # Create a shared 'Foo' object
  my $foo :shared = shared_clone({});
  bless($foo, 'Foo');

  # Create a shared 'Bar' object
  my $bar :shared = shared_clone({});
  bless($bar, 'Bar');

  # Put 'bar' inside 'foo'
  $foo->{'bar'} = $bar;

  # Rebless the objects via a thread
  threads->create(sub {
      # Rebless the outer object
      bless($foo, 'Yin');

      # Cannot directly rebless the inner object
      #bless($foo->{'bar'}, 'Yang');

      # Retrieve and rebless the inner object
      my $obj = $foo->{'bar'};
      bless($obj, 'Yang');
      $foo->{'bar'} = $obj;

  })->join();

  print(ref($foo),          "\n");    # Prints 'Yin'
  print(ref($foo->{'bar'}), "\n");    # Prints 'Yang'
  print(ref($bar),          "\n");    # Also prints 'Yang'

注意¶

threads が利用できない場合、threads::shared は黙って利用不可になるよう 設計されています。 これにより、スレッドと非スレッドの両方のアプリケーションで使えるモジュールと パッケージを書けます。

threads にアクセスしようとするなら、use threads::shared する前に use threads しなければなりません。 threads::shared の後に threads を use しようとすれば、警告が 発せられます。

バグと制限¶

share が配列、ハッシュ、配列リファレンス、ハッシュリファレンスで 使われると、含まれるあらゆるデータは失われます。

  my @arr = qw(foo bar baz);
  share(@arr);
  # @arr is now empty (i.e., == ());

  # Create a 'foo' object
  my $foo = { 'data' => 99 };
  bless($foo, 'foo');

  # Share the object
  share($foo);        # Contents are now wiped out
  print("ERROR: \$foo is empty\n")
      if (! exists($foo->{'data'}));

従って、このような変数は、共有すると宣言した 後に 設定してください。 (スカラとスカラリファレンスはこの問題の影響を受けません。)

クラス自身が共有に対応するように書かれていないオブジェクトを共有することは たいてい賢明なこととは言えません。 例えば、各スレッドのスコープから外れる毎に、あるオブジェクトの デストラクタが複数回呼び出されるかも知れません。 もう一つの危険性は、ハッシュベースのオブジェクトの内容が、上述した 制限のために失われてしまうことです。 オブジェクト共有に対応したクラスの作り方については、(このモジュールの CPAN 配布に含まれている examples/class.pl を参照してください。

配列に対する splice はサポートしていません!

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

share($hashref->{key}) や share($arrayref->[idx]) しても、 share() はエラーメッセージを出しません。 しかし、$hashref->{key} や $arrayref->[idx] は共有 されません; 他のスレッドで lock($hashref->{key}) や lock($arrayref->[idx]) しようとすれば "locking can only be used on shared values" (ロックは共有変数に対してのみ 使用できます) というエラーが発生します。

refaddr()) の使用は、二つの共有リファレンスが 等価かどうかをテストする (例えば循環参照をテストする) には信頼性が ありません。 代わりに "is_shared VARIABLE" in is_shared() を使ってください:

    use threads;
    use threads::shared;
    use Scalar::Util qw(refaddr);

    # If ref is shared, use threads::shared's internal ID.
    # Otherwise, use refaddr().
    my $addr1 = is_shared($ref1) || refaddr($ref1);
    my $addr2 = is_shared($ref2) || refaddr($ref2);

    if ($addr1 == $addr2) {
        # The refs are equivalent
    }

each() は共有構造体に組み込まれた共有リファレンスには 正しく動作しません。 例えば:

    my %foo :shared;
    $foo{'bar'} = shared_clone({'a'=>'x', 'b'=>'y', 'c'=>'z'});

    while (my ($key, $val) = each(%{$foo{'bar'}})) {
        ...
    }

しかし以下のどちらかは動作します:

    my $ref = $foo{'bar'};
    while (my ($key, $val) = each(%{$ref})) {
        ...
    }

    foreach my $key (keys(%{$foo{'bar'}})) {
        my $val = $foo{'bar'}{$key};
        ...
    }

既に報告されているバグの閲覧や、新しいバグ、問題、パッチなどの投稿先: http://rt.cpan.org/Public/Dist/Display.html?Name=threads-shared

SEE ALSO¶

CPAN の threads::shared ディスカッションフォーラム: http://www.cpanforum.com/dist/threads-shared

threads::shared の注釈付き POD: http://annocpan.org/~JDHEDDEN/threads-shared-1.29/shared.pm

ソースレポジトリ: http://code.google.com/p/threads-shared/

threads, perlthrtut

http://www.perl.com/pub/a/2002/06/11/threads.html と http://www.perl.com/pub/a/2002/09/04/threads.html

Perl threads メーリングリスト: http://lists.cpan.org/showlist.cgi?name=iThreads

作者¶

Artur Bergman <sky AT crucially DOT net>

Documentation borrowed from the old Thread.pm.

CPAN version produced by Jerry D. Hedden <jdhedden AT cpan DOT org>.

ライセンス¶

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