=encoding euc-jp =head1 名前 Thread::Conveyor - スレッド間における任意のデータ構造の移送 =head1 概要 use Thread::Conveyor; my $belt = Thread::Conveyor->new( { maxboxes => 50, minboxes => 25, optimize => 'memory', # または 'cpu' } ); $belt->put( "foo", ["bar"], {"zoo"} ); my ($foo,$bar,$zoo) = $belt->take; my ($foo,$bar,$zoo) = $belt->take_dontwait; my ($foo,$bar,$zoo) = $belt->peek; my ($foo,$bar,$zoo) = $belt->peek_dontwait; my $onbelt = $belt->onbelt; my @box = $belt->clean; my @box = $belt->clean_dontwait; my ($foo,$bar,$zoo) = @{$box[0]}; $belt->maxboxes( 100 ); $belt->minboxes( 50 ); $belt->shutdown; $belt->thread; $belt->tid; =head1 説明 *** A note of CAUTION *** This module only functions on Perl versions 5.8.0 and later. And then only when threads are enabled with -Dusethreads. It is of no use with any version of Perl before 5.8.0 or without threads enabled. ************************* *** 注 意 書 き *** このモジュールはPerl 5.8.0とそれ以降でのみ機能する。 かつ、-Dusethreadsでスレッドが有効になっている場合だけである。 5.8.0より前のバージョン、あるいはスレッド機能が有効になって いない場合は、利用できない。 ************************* The Thread::Conveyor object is a thread-safe data structure that mimics the behaviour of a conveyor belt. One or more worker threads can put boxes with frozen values and references on one end of the belt to be taken off by one or more worker threads on the other end of the belt to be thawed and returned. Thread::Conveyorオブジェクトは、ベルトコンベアの振る舞いをまねた スレッドセーフなデータ構造である。一つ以上のワーカースレッドが凍結された 値やリファレンスの入った箱をベルトの一方の端に置く。そしてベルトの 他方の端で一つ以上のワーカースレッドがその箱を取り除き、解凍して返す。 A box may consist of any combination of scalars and references to scalars, arrays (lists) and hashes. Freezing and thawing is currently done with the L module, but that may change in the future. Objects and code references are currently B allowed. 一つの箱はスカラーおよび、スカラー、配列（リスト）そしてハッシュへの リファレンスのコンビネーションで構成される。凍結と解凍は現在のところ Lモジュールを使ってなされる。しかし将来は変更されるかも しれない。オブジェクトとコードリファレンスは現在のところ許されB<ない>。 By default, the maximum number of boxes on the belt is limited to B<50>. Putting of boxes on the belt is halted if the maximum number of boxes is exceeded. This throttling feature was added because it was found that excessive memory usage could be caused by having the belt growing too large. Throttling can be disabled if so desired. デフォルトでは、ベルト上の箱の最大値はB<50>に制限される。箱の最大値を 超過した場合、ベルトに箱を置く作業は停止する。この抑制機能（スロットル）を 追加したのは、ベルトが非常に大きくなることによって過度のメモリ消費が発生 することに気付いたからである。もしそう望むならスロットルを無効にできる。 =head1 クラスメソッド =head2 new $belt = Thread::Conveyor->new( { maxboxes => 50, minboxes => 25, optimize => 'memory', # あるいは 'cpu' } ); The "new" function creates a new empty belt. It returns the instantiated Thread::Conveyor object. "new"関数は新しい空のベルトを生成する。初期化されたThread::Conveyor オブジェクトを返す。 The input parameter is a reference to a hash. The following fields are B in the hash reference: 入力するパラメータはハッシュのリファレンスである。以下のフィールドが ハッシュリファレンス内のB<オプション>： =over 2 =item maxboxes maxboxes => 50, maxboxes => undef, # スロットルを無効にする The "maxboxes" field specifies the B number of boxes that can be sitting on the belt to be handled (throttling). If a new L would exceed this amount, putting of boxes will be halted until the number of boxes waiting to be handled has become at least as low as the amount specified with the "minboxes" field. "maxboxes"フィールドはベルトに据えられる箱のB<最大>値を指定し、 制御（スロットル）を行う。もし新たなLがこの値を超過した場合、 制御されるために待っている箱の数が少なくとも"minboxes"フィールドで 指定された値に下がるまで、箱を置く作業は停止する。 Fifty boxes will be assumed for the "maxboxes" field if it is not specified. If you do not want to have any throttling, you can specify the value "undef" for the field. But beware! If you do not have throttling active, you may wind up using excessive amounts of memory used for storing all of the boxes that have not been handled yet. 何も指定しないなら"maxboxes"フィールドは50箱と見なされる。もしスロットル を望まないなら、フィールドに"undef"を指定する。だけど気を付けて！　 スロットルを活動させないと、もはや制御の効かない箱を全て保持するために 大量のメモリを消費するはめになるかもしれない。 The L method can be called to change the throttling settings during the lifetime of the object. ベルトオブジェクトが生きている間、Lメソッドを呼び出して スロットルの設定を変更できる。 =item minboxes minboxes => 25, # default: maxboxes / 2 The "minboxes" field specifies the B number of boxes that can be waiting on the belt to be handled before the Lting of boxes is allowed again (throttling). "minboxes"フィールドは、箱に対するLが再度許可される前に ベルト上で制御（スロットル）されるのを待っている箱のB<最小>値を指定する。 If throttling is active and the "minboxes" field is not specified, then half of the "maxboxes" value will be assumed. スロットルが活性化していて、かつ"minimumboxes"フィールドが指定されていない 場合、"maxboxes"の値の半分が仮定される。 The L method can be called to change the throttling settings during the lifetime of the object. ベルトオブジェクトが生きている間、Lメソッドを読んでスロットルの 設定を変更できる。 =item optimize optimize => 'cpu', # デフォルト：Perlのバージョンによる The "optimize" field specifies which implementation of the belt will be selected. Currently there are two choices: 'cpu' and 'memory'. For Perl 5.8.0 the default is "memory". For higher versions of perl, the default optimization is "cpu". The reason for this was that Perl 5.8.0 has a severe memory leak with shared arrays, which is what is being used with the "cpu" optimization. "optimize"フィールドは、ベルトの実装をどちらにするか指定する。現在のところ、 二つの選択肢がある：'cpu'と'memory'だ。Perl 5.8.0ではデフォルトで"memory"に なる。それ以上のバージョンでは、デフォルトは"cpu"になる。このようにした 理由は、Perl 5.8.0が共有配列で深刻なメモリリークを引き起こし、"cpu"最適化を 使うとそれが起きるからである。 You can call the class method L to change the default optimization. クラスメソッドLを呼べば、デフォルトの最適化を変更できる。 =back =head2 optimize Thread::Conveyor->optimize( 'cpu' ); $optimize = Thread::Conveyor->optimize; The "optimize" class method allows you to specify the default optimization type that will be used if no "optimize" field has been explicitely specified with a call to L. It returns the current default type of optimization. "optimize"クラスメソッドを使えば、デフォルトの最適化タイプを指定できるので、 Lを呼んだときに明示的に"optimize"フィールドを指定しなくても、それを 使うことができる。現在の最適化のデフォルトタイプを返す。 Currently two types of optimization can be selected: 現状では二つのタイプの最適化を選択できる： =over 2 =item memory Attempt to use as little memory as possible. Currently, this is achieved by starting a seperate thread which hosts an unshared array. This uses the "Thread::Conveyor::Thread" sub-class. 可能な限り少なくメモリを使おうと試みる。現在、この機能は非共有配列のホスト となる独立したスレッドを開始することによって達成している。これには "Thread::Conveyor::Thread"サブクラスを用いる。 =item cpu Attempt to use as little CPU as possible. Currently, this is achieved by using a shared array (using the "Thread::Conveyor::Array" sub-class), encapsulated in a hash reference if throttling is activated (then also using the "Thread::Conveyor::Throttled" sub-class). 可能な限りCPUを少なく使おうと試みる。現在、この機能は共有配列を使うことに よって達成している（"Thread::Conveyor::Array"サブクラスを利用）。もし スロットルが活性化しているなら、ハッシュリファレンスの中にカプセル化 される（そのときは"Thread::Conveyor::Throttled"サブクラスも利用する）。 =back =head1 オブジェクトメソッド The following methods operate on the instantiated Thread::Conveyor object. 以下のメソッドは、初期化されたThread::Conveyorオブジェクトに対し操作する。 =head2 put $belt->put( 'string',$scalar,[],{} ); The "put" method freezes all the specified parameters together in a box and puts the box on the beginning of the belt. "put"メソッドは、指定したパラメータを全て一緒に箱の中で凍結し、その箱を ベルトの始まりに置く。 =head2 take ($string,$scalar,$listref,$hashref) = $belt->take; The "take" method waits for a box to become available at the end of the belt, removes that box from the belt, thaws the contents of the box and returns the resulting values and references. "take"メソッドは、ある箱がベルトの端で利用可能になるまで待ち、その箱を ベルトから取り除き、箱の中身を解凍し、その結果の値やリファレンスを返す。 =head2 take_dontwait ($string,$scalar,$listref,$hashref) = $belt->take_dontwait; The "take_dontwait" method, like the L method, removes a box from the end of the belt if there is a box waiting at the end of the belt. If there is B box available, then the "take_dontwait" method will return immediately with an empty list. Otherwise the contents of the box will be thawed and the resulting values and references will be returned. "take_dontwait"メソッドは、Lメソッド同様、ベルトの最後で待っている箱が あるなら、箱をベルトの端から取り除く。利用可能な箱がB<ない>場合、 "take_dontwait"メソッドは直ちに空リストを返す。それ以外なら箱の中身は 解凍され、結果の値やリファレンスが返される。 =head2 clean @box = $belt->clean; ($string,$scalar,$listref,$hashref) = @{$box[0]}; The "clean" method waits for one or more boxes to become available at the end of the belt, removes B boxes from the belt, thaws the contents of the boxes and returns the resulting values and references as an array where each element is a reference to the original contents of each box. "clean"メソッドは、ベルトの最後で一つ以上の箱が利用可能になるまで待ち、 ベルトからB<全ての>箱を取り除き、箱の中身を解凍し、結果の値やリファレンスを 配列として返す。この配列の各要素は、各箱の元の内容へのリファレンスである。 =head2 clean_dontwait @box = $belt->clean_dontwait; ($string,$scalar,$listref,$hashref) = @{$box[0]}; The "clean_dontwait" method, like the L method, removes all boxes from the end of the belt if there are any boxes waiting at the end of the belt. If there are B boxes available, then the "clean_dontwait" method will return immediately with an empty list. Otherwise the contents of the boxes will be thawed and the resulting values and references will be returned an an array where each element is a reference to the original contents of each box. "clean_dontwait"メソッドは、L同様、ベルトの最後で待っている箱が あるなら、ベルトの端から全ての箱を取り除く。もし利用可能な箱がB<ない>なら、 "clean_dontwait"メソッドは直ちに空リストを返す。それ以外の場合、箱の中身は 解凍され、結果の値やリファレンスは配列として返される。この配列の各要素は、 各箱の元の内容へのリファレンスである。 =head2 peek ($string,$scalar,$listref,$hashref) = $belt->peek; @lookahead = $belt->peek( $index ); The "peek" method waits for a box to become availabe at the end of the belt, but does B remove it from the belt like the L method does. It does however thaw the contents and returns the resulting values and references. "peek"メソッドは、ベルトの最後で箱が利用可能になるまで待つ。しかし、L メソッドとは違い、ベルトから箱をB<取り除かない>。だが、内容を解凍し、 結果の値やリファレンスは返す。 For advanced, and mostly internal, usages, it is possible to specify the ordinal number of the box in which to peek. さらに進んだ、ほとんど内部的な利用方法として、のぞき見する箱の序数が 指定可能だ。 Please note that there is B guarantee that "take" will give you the same data as which is returned with this method, as any other thread can have taken the boxes off of the belt in the meantime. 注意して貰いたいのは、このメソッドが返したデータと同じものを"take"が 返すことはB<保証されていない>ということである。というのも、他のスレッドが、 その間にベルトから箱を取り除く可能性があるからだ。 =head2 peek_dontwait ($string,$scalar,$listref,$hashref) = $belt->peek_dontwait; @lookahead = $belt->peek_dontwait( $index ); The "peek_dontwait" method is like the L method, but does B remove the box from the belt if there is one available. If there is a box available, then the contents of the box will be thawed and the resulting values and references are returned. An empty list will be returned if there was no box available at the end of the belt. "peek_dontwait"メソッドは、Lメソッドに似ている。ただし 箱が利用可能な場合、ベルトから箱をB<取り除かない>。箱が利用可能なら、 箱の中身は解凍され、結果の値やリファレンスが返される。もしベルトの最後に 利用可能な箱が内なら、空リストが返される。 For advanced, and mostly internal, usages, it is possible to specify the ordinal number of the box in which to peek. さらに進んだ、ほとんど内部的な利用方法として、のぞき見する箱の序数を指定 可能だ。 Please note that there is B guarantee that "take" will give you the same data as which is returned with this method, as any other thread can have taken the boxes off of the belt in the meantime. 注意して貰いたいのは、このメソッドが返したデータと同じものを"take"が 返すことはB<保証されていない>ということである。というのも、他のスレッドが、 その間にベルトから箱を取り除く可能性があるからだ。 =head2 onbelt $onbelt = $belt->onbelt; The "onbelt" method returns the number of boxes that are still in the belt. "onbelt"メソッドは、まだベルトに残っている箱の数を返す。 =head2 maxboxes $belt->maxboxes( 100 ); $maxboxes = $belt->maxboxes; The "maxboxes" method returns the maximum number of boxes that can be on the belt before throttling sets in. The input value, if specified, specifies the new maximum number of boxes that may be on the belt. Throttling will be switched off if the value B is specified. "maxboxes"メソッドは、スロットルが開始されるまでベルトの上に載せられる 箱の最大値を返す。入力値が指定されると、新たな最大値が設定される。 入力値にBを指定することで、スロットルのスイッチが切られる。 Specifying the "maxboxes" field when creating the object with L is equivalent to calling this method. Lを使ってオブジェクトを生成する時に"maxboxes"フィールドを指定するのは、 このメソッドを呼び出すのに等しい。 The L method can be called to specify the minimum number of boxes that must be on the belt before the putting of boxes is allowed again after reaching the maximum number of boxes. By default, half of the "maxboxes" value is assumed. Lメソッドは、箱が最大値に達した後、再び箱を置くのが許可される までの、ベルト上になければならない箱の最小値を設定するために呼び出される。 デフォルトでは、"maxboxes"の半分の値が想定される。 =head2 minboxes $belt->minboxes( 50 ); $minboxes = $belt->minboxes; The "minboxes" method returns the minimum number of boxes that must be on the belt before the putting of boxes is allowed again after reaching the maximum number of boxes. The input value, if specified, specifies the new minimum number of boxes that must be on the belt. "minboxes"メソッドは、箱が最大値に達した後、再び箱を置くのが許可される までの、ベルト上になければならない箱の最小値を返す。入力値を指定すると、 新たな最小値が設定される。 Specifying the "minboxes" field when creating the object with L is equivalent to calling this method. Lを使ってオブジェクトを生成する時に"minboxes"フィールドを指定するのは、 このメソッドを呼び出すのに等しい。 The L method can be called to set the maximum number of boxes that may be on the belt before the putting of boxes will be halted. Lメソッドを呼び出すと、箱の設置が停止するまでにベルト上に存在 できる箱の最大値を設定できる。 =head2 shutdown $belt->shutdown; The "shutdown" method performs an orderly shutdown of the belt. It waits until all of the boxes on the belt have been removed before it returns. "shutdown"メソッドは、ベルトの操業を正常に停止させる。このメソッドは 戻る前に、ベルト上の箱が全て取り除かれるまで待ちに入る。 =head2 thread $thread = $belt->thread; The "thread" method returns the thread object that is being used for the belt. It returns undef if no seperate thread is being used. "thread"メソッドは、そのベルトを使っているスレッドオブジェクトを返す。 どのスレッドも利用していないならundefを返す。 =head2 tid $tid = $belt->tid; The "tid" method returns the thread id of the thread object that is being used for the belt. It returns undef if no seperate thread is being used. "tid"メソッドは、そのベルトを利用しているスレッドオブジェクトのスレッド idを返す。どのスレッドも利用していないならundefを返す。 =head1 必要なモジュール load (どのバージョンでも) Thread::Serialize (どのバージョンでも) Thread::Tie (0.09) =head1 最適化 This module uses L to reduce memory and CPU usage. This causes subroutines only to be compiled in a thread when they are actually needed at the expense of more CPU when they need to be compiled. Simple benchmarks however revealed that the overhead of the compiling single routines is not much more (and sometimes a lot less) than the overhead of cloning a Perl interpreter with a lot of subroutines pre-loaded. このモジュールはLを使ってメモリとCPUの消費を縮小している。これに よって、サブルーチンは、実際に必要となるときにだけスレッド内でコンパイル される。このコンパイルのためにより多くのCPUを犠牲にする。しかし単純な ベンチマークによると、一つのルーチンをコンパイルするオーバーヘッドは 予めロードされた大量のサブルーチンを伴うPerlインタプリタをクローンする オーバーヘッドよりもそれほど多くはない（そして時には非常に少なくなる）ことが 明らかになっている。 =head1 警告 Passing unshared values between threads is accomplished by serializing the specified values using L. Please see the CAVEATS section there for an up-to-date status of what can be passed around between threads. スレッド間で非共有の値を渡すのは、Lを使って指定の値を シリアル化することで達成している。スレッド間で何を渡せるかの最新状況に ついては、そちらのモジュールの注意セクションを参照して欲しい。 =head1 作者 Elizabeth Mattijsen, . Please report bugs to . =head1 歴史 This module started life as L and as a sub-class of L. Using the conveyor belt metaphore seemed more appropriate and therefore the name was changed. To cut the cord with Thread::Queue completely, the belt mechanism was implemented from scratch. このモジュールはLとして、そしてLの サブクラスとして、誕生した。ベルトコンベアの比喩はより適したものに思えた ので、名前を変えた。Thread::Queueのコードを完全に断ち切るために、ベルトの メカニズムは一から実装した。 Why would you use Thread::Conveyor over Thread::Queue::Any? Well, Thread::Conveyor has the following extra features: なぜThread::Queue::AnyよりThread::Conveyorを使うのか？　ええと、 Thread::Conveyorには以下の付加的な特徴があるのだ： =over 2 =item It works with Perl 5.8.0 Perl 5.8.0で動作する Shared arrays leak memory very badly in Perl 5.8.0. Therefore, you cannot really use Thread::Queue in Perl 5.8.0, and consequently cannot use Thread::Queue::Any in any type of production environment. Perl 5.8.0では共有配列が大変まずい具合にメモリリークを起こす。それゆえ、 本当はPerl 5.8.0ではThread::Queueは使えない。そしてその結果、 どんなプロダクション環境タイプでも、Thread::Queue::Anyは使えない。 =item It provides throttling スロットルの提供 A thread that enqueues very many values quickly, can cause a large amount of memory to be used. With throttling, any thread that enqueues will have to wait until there is "room" on the belt again before continuing. See methods "minboxes" and "maxboxes". スレッドが急に大変多くの値をキューに入れると、大量のメモリが消費される。 スロットルを使うことで、キューに入れようとするスレッドは作業を続ける前に、 ベルトに"余裕"ができるまで、待たなければならない。メソッド"minboxes"と "maxboxes"を参照されたし。 =item You can check for a new value without removing it from the belt ベルトから取り除くことなしに新しい値をチェックできる Sometimes it can be nice to check whether there is a new value on the belt without actually removing it from the belt. See the "peek" and "peek_dontwait" methods. 実際にベルトから取り除かずに、ベルト上に新しい値があるかどうかを調べると 良いことが、時々ある。"peek"と"peek_dontwait"メソッドを参照されたし。 =item You can reset the entire belt ベルトを丸ごとリセットできる Sometimes you want to be able to reset the contents of the belt. See the "clean" and "clean_dontwait" methods for that. 時にはベルトの中身をリセットしたいと思うだろう。そのためにはメソッド "clean"と"clean_dontwait"を参照されたし。 =item You can get everything from the belt in one go 一気にベルトから全てを得られる Sometimes you want everything that's on the belt in one go. That can also ba accomplished with the "clean" and "clean_dontwait" methods. 時にはベルト上にある全てのものを一気に欲しいと思うだろう。これもまた "clean"と"clean_dontwait"メソッドを使って達成できる。 =back =head1 著作権 Copyright (c) 2002-2004 Elizabeth Mattijsen . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 参照 L, L, L, L, L.