=encoding euc-jp =head1 名前 Thread::Conveyor::Monitored - 特定の内容のためにベルトを監視する =head1 概要 use Thread::Conveyor::Monitored; my $mbelt = Thread::Conveyor::Monitored->new( { monitor => sub { print "monitoring value $_[0]\n" }, # is a must pre => sub { print "prepare monitoring\n" }, # optional post => sub { print "stop monitoring\n" }, # optional belt => $belt, # use existing belt, create new if not specified exit => 'exit', # defaults to undef checkpoint => sub { print "checkpointing\n" }, frequency => 1000, optimize => 'memory', # optimization maxboxes => 50, # specify throttling minboxes => 25, # parameters } ); $mbelt->put( "foo",['listref'],{'hashref'} ); $mbelt->put( undef ); # exit value by default $mbelt->shutdown; $mthread = $mbelt->thread; $mtid = $mbelt->tid; $belt = $mbelt->belt; @post = $mthread->join; # optional, wait for monitor thread to end $belt = Thread::Conveyor::Monitored->belt; # "pre", "do", "post" =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. ************************* The C module implements a single worker thread that takes of boxes of values from a belt created with L and which checks the boxes for specific content. Cモジュールは、Lで生成された ベルトから、値の詰まった箱を取り出すシングルワーカースレッドを実装する。 このワーカースレッドはその箱が特定の内容かどうかチェックする。 It can be used for simply logging actions that are placed on the belt. Or only output warnings if a certain value is encountered in a box. Or create a safe sandbox for Perl modules that are not thread-safe yet. このモジュールは、ベルトの上で起こるアクションを単純に記録するために使える。 あるいは箱の中にある値が出現したら警告を発生させるのに、あるいは、未だに スレッドセーフでないPerlモジュール用に安全なsandboxを生成するのに使える。 The action performed in the thread, is determined by a name or reference to a subroutine. This subroutine is called for every box of values obtained from the belt. このスレッドがとるアクションは、サブルーチンへの名前かリファレンスによって 決定する。ベルトから取得される値の詰まった箱毎に、そのサブルーチンが呼び 出される。 Any number of threads can safely put boxes with values and reference on the belt. 任意の数のスレッドが、値やリファレンスの入った箱をベルトの上に置ける。 Optional checkpointing allows you to check and save intermediate status. オプションのチェックポイントを使うことで、中間状態を調べたりセーブしたりできる。 =head1 クラスメソッド =head2 new $mbelt = Thread::Conveyor::Monitored->new( { pre => \&pre, monitor => 'monitor', post => \&module::post, belt => $belt, # use existing belt, create new if not specified exit => 'exit', # defaults to undef checkpoint => \&checkpoint, frequency => 1000, optimize => 'memory', maxboxes => 50, minboxes => 25, }, @parameters ); The C function creates a monitoring function on an existing or on a new (empty) belt. It returns the instantiated Thread::Conveyor::Monitored object. C関数は、既にある、あるいは新しい(空の)ベルトに対する監視機能を 生成する。インスタンスとなったThread::Conveyor::Monitoredオブジェクトを返す。 The first input parameter is a reference to a hash that should at least contain the "monitor" key with a subroutine reference. 一番目の入力パラメータはハッシュリファレンスで、少なくともサブルーチン リファレンスを伴った"monitor"キーが含まれる。 The other input parameters are optional. If specified, they are passed to the the "pre" routine which is executed once when the monitoring is started. それ以外の入力パラメータはオプションである。指定すれば、監視が始まるさいに 一度だけ実行される"pre"ルーチンに渡される。 The following field B be specified in the hash reference: 以下のフィールドはハッシュリファレンス内でB<指定しなければならない>: =over 2 =item do monitor => 'monitor_the_belt', # 呼び出し側の名前空間を想定 or: あるいは: monitor => 'Package::monitor_the_belt', or: あるいは: monitor => \&SomeOther::monitor_the_belt, or: あるいは: monitor => sub {print "anonymous sub monitoring the belt\n"}, The "monitor" field specifies the subroutine to be executed for each set of values that is removed from the belt. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine. "monitor"フィールドは、ベルトから取り除かれた値の各セット毎に対して実行される サブルーチンを指定する。サブルーチンの名前か、(無名)サブルーチンへの リファレンスのいずれかで指定しなければならない。 The specified subroutine should expect the following parameters to be passed: 指定したサブルーチンは、以下のパラメータが渡されることを期待する: 1..N set of values obtained from the box on the belt ベルト上の箱から取り出した1..Nまでの値のセット What the subroutine does with the values, is entirely up to the developer. 値に対してサブルーチンが何をするのかは、完全に開発者まかせである。 =back The following fields are B in the hash reference: ハッシュリファレンス内において、以下のフィールドはB<オプション>である: =over 2 =item pre pre => 'prepare_monitoring', # 呼び出し側の名前空間を想定 or: あるいは: pre => 'Package::prepare_monitoring', or: あるいは: pre => \&SomeOther::prepare_monitoring, or: あるいは: pre => sub {print "anonymous sub preparing the monitoring\n"}, The "pre" field specifies the subroutine to be executed once when the monitoring of the belt is started. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine. "pre"フィールドは、ベルトの監視が開始されるさいに一度だけ実行される サブルーチンを指定する。サブルーチンの名前か、(無名)サブルーチンへの リファレンスのいずれかで指定しなければならない。 The specified subroutine should expect the following parameters to be passed: 指定したサブルーチンは、以下のパラメータが渡されることを期待する: 1..N any extra parameters that were passed with the call to L. Lを呼び出したときに渡された1..N個の追加パラメータ =item post post => 'stop_monitoring', # 呼び出し側の名前空間を想定 or: あるいは: post => 'Package::stop_monitoring', or: あるいは: post => \&SomeOther::stop_monitoring, or: あるいは: post => sub {print "anonymous sub when stopping the monitoring\n"}, The "post" field specifies the subroutine to be executed once when the monitoring of the belt is stopped. It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine. "post"フィールドは、ベルトの監視が停止したさいに一度だけ実行される サブルーチンを指定する。サブルーチンの名前か、(無名)サブルーチンへの リファレンスのいずれかで指定しなければならない。 The specified subroutine should expect the following parameters to be passed: 指定したサブルーチンは、以下のパラメータが渡されることを期待する: 1..N any parameters that were passed with the call to L. Lを呼び出したときに渡した1..N個の任意のパラメータ Any values returned by the "post" routine, can be obtained with the C method on the thread object. "post"ルーチンから返されたどんな値も、このスレッドオブジェクトが持つ Cメソッドで取得できる。 =item belt belt => $belt, # 指定しなければ新規のベルトが生成される The "belt" field specifies the Thread::Conveyor object that should be monitored. A new L object will be created if it is not specified. "belt"フィールドは、監視されるThread::Conveyorオブジェクトを指定する。 指定しなければ、新たにLオブジェクトが生成される。 =item exit exit => 'exit', # デフォルトはundef The "exit" field specifies the value that will cause the monitoring thread to seize monitoring. The "undef" value will be assumed if it is not specified. This value should be L in a box on the belt to have the monitoring thread stop. "exit"フィールドは、監視スレッドの監視を止めさせる値を指定する。 何も指定しなければ、"undef"が想定される。この値は、ベルト上の箱にLされ、 監視スレッドを停止させる。 =item checkpoint checkpoint => 'checkpointing', # 呼び出し側の名前空間を想定 or: あるいは: checkpoint => 'Package::checkpointing', or: あるいは: checkpoint => \&SomeOther::checkpointing, or: あるいは: checkpoint => sub {print "anonymous sub to do checkpointing\n"}, The "checkpoint" field specifies the subroutine to be executed everytime a checkpoint should be made (e.g. for saving or updating status). It must be specified as either the name of a subroutine or as a reference to a (anonymous) subroutine. "checkpoint"フィールドは、チェックポイントがつくられる度に実行される サブルーチンを指定する(例えば、状態のセーブや更新)。サブルーチンの名前か、 (無名)サブルーチンへのリファレンスのいずれかで指定しなければならない。 No checkpointing will occur by default. The frequency of checkpointing can be specified with the "frequency" field. デフォルトではチェックポイントは現れない。チェックポイントの頻度は、 "frequency"フィールドで指定できる。 The specified subroutine should not expect any parameters to be passed. Any values returned by the checkpointing routine, will be lost. この指定されたサブルーチンは、パラメータが渡されることを想定しない。 チェックポイントルーチンが返すどんな値も失われる。 =item frequency frequency => 100, # デフォルト = 1000 The "frequency" field specifies the number of boxes that should have been monitored before the "checkpoint" routine is called. If a checkpoint routine is specified but no frequency field is specified, then a frequency of B<1000> will be assumed. "frequency"フィールドは、"checkpoint"ルーチンが呼び出されるまでに監視される 箱の数を指定する。チェックポイントルーチンが指定されているのに、frequency フィールドが指定されていない場合、frequencyにはB<1000>が想定される。 This field has no meaning if no checkpoint routine is specified with the "checkpoint" field. The default frequency can be changed with the L method. "checkpoint"フィールドでチェックポイントルーチンが指定されていなければ、 このフィールドは意味がない。デフォルトのfrequencyはLメソッドで 変更できる。 =item optimize optimize => 'cpu', # デフォルト:'memory' The "optimize" field specifies which implementation of the belt will be selected if there is no existing belt specified with the 'belt' field. Currently there are two choices: 'cpu' and 'memory'. By default, the "memory" optimization will be selected if no specific optmization is specified. "optimize"フィールドは、既存のベルトが"belt"フィールドで指定されていない 場合に、どちらのベルトの実装を選択するか指定する。現在のところ二つの選択肢: 'cpu'と'memory'がある。デフォルトでは、最適化の指定がない場合に、"memory"が 選択される。 You can call the class method L to change the default optimization. クラスメソッドLを呼ぶことで、デフォルトの最適化を変更できる。 =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. 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. The L method can be called to change the throttling settings during the lifetime of the object. =item minboxes minboxes => 25, # デフォルト:maxboxes / 2 The "minboxes" field specified the B number of boxes that can be waiting on the belt to be handled before the Lting of boxes is allowed again (throttling). If throttling is active and the "minboxes" field is not specified, then half of the "maxboxes" value will be assumed. The L method can be called to change the throttling settings during the lifetime of the object. =back =head2 belt $belt = Thread::Conveyor::Monitored->belt; # only within "pre" and "do" The class method "belt" returns the L::xxx object that this thread is monitoring. It is available within the "pre" and "do" subroutine only. クラスメソッドの"belt"は、このスレッドが監視するL::xxx オブジェクトを返す。"pre"と"do"サブルーチンの中でのみ利用可能だ。 =head2 frequency Thread::Conveyor::Monitored->frequency( 100 ); $frequency = Thread::Conveyor::Monitored->frequency; The "frequency" class method allows you to specify the default frequency that will be used when a checkpoint routine is specified with the "checkpoint" field. The default frequency is set to B<1000> if no other value has been previously specified. =head2 optimize Thread::Conveyor::Monitored->optimize( 'cpu' ); $optimize = Thread::Conveyor::Monitored->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. 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. =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). =back =head1 オブジェクトメソッド =head2 put $mbelt->put( $scalar,[],{} ); $mbelt->put( 'exit' ); # 監視を停止する The "put" method freezes all specified parameters in a box and puts it on the belt. The monitoring thread will stop monitoring if the "exit" value is put in the box. "put"メソッドは箱の中で指定した全てのパラメータを凍結し、ベルトの上に 載せる。"exit"値が箱の中に入れられると、監視スレッドは監視を停止する。 Please note that if you need to be very efficient, it may be wortwhile to extract the actual L object first and use that to put boxes on the belt. The monitored "put" method is in fact only a gateway to the actual belt that is inside this object. 注意して欲しいのだが、あなたが効率性を求めるなら、最初に実際のL オブジェクトを抜き出し、そのオブジェクトを使ってベルトの上に箱を置く方が 有効かもしれない。監視された"put"メソッドは実際のところ、オブジェクト内に ある実際のベルトのゲートウェイに過ぎない。 =head2 maxboxes $mbelt->maxboxes( 100 ); $maxboxes = $mbelt->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. Specifying the "maxboxes" field when creating the object with L is equivalent to calling this method. 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. =head2 minboxes $mbelt->minboxes( 50 ); $minboxes = $mbelt->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. Specifying the "minboxes" field when creating the object with L is equivalent to calling this method. 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. =head2 belt $belt = $mbelt->belt; The "belt" instance method returns the L::xxx object that is being monitored. インスタンスメソッドの"belt"は、監視されているL::xxx オブジェクトを返す。 =head2 frequency $frequency = $mbelt->frequency; The "frequency" instance method returns the frequency with which the checkpoint routine is being called. Returns undef if no checkpointing is being done. =head2 shutdown $mbelt->shutdown; @from_monitor_thread = $mbelt->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. Whatever was returned by the "post" routine of the monitoring thread, will also be returned by the "shutdown" method. 監視スレッドの"post"ルーチンが返す値はそれが何であれ、"shutdown"メソッドに よっても返される。 =head2 thread $mthread = $mbelt->thread; The "thread" method returns the thread object that is monitoring the contents of the belt. "thread"メソッドは、ベルトの内容を監視しているスレッドオブジェクトを返す。 =head2 tid $tid = $mbelt->tid; The "tid" method returns the thread id of the thread object that is monitoring the contents of the belt. "tid"メソッドは、ベルトの内容を監視しているスレッドオブジェクトのスレッドidを 返す。 =head1 必要なモジュール load (どのバージョンでも) Thread::Conveyor (0.15) =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. =head1 警告 You cannot remove any boxes from the belt, as that is done by the monitoring thread. Therefore, the methods "take", "take_dontwait", "peek" and "peek_dontwait" are disabled on this object. ベルトからいかなる箱も取り除くことはできない。といのも、それは監視している スレッドによってなされるからだ。それゆえ、このオブジェクト上では "take"、"take_dontwait"、"peek"そして"peek_dontwait"は使えない。 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. =head1 作者 Elizabeth Mattijsen, . Please report bugs to . =head1 著作権 Copyright (c) 2002-2003 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.