=encoding euc-jp

=head1 名前

Thread::Queue::Any - 任意のデータ構造に対するスレッドセーフなキュー

=head1 概要

    use Thread::Queue::Any;
    my $q = Thread::Queue::Any->new;
    $q->enqueue("foo", ["bar"], {"zoo"});
    my ($foo,$bar,$zoo) = $q->dequeue;
    my ($foo,$bar,$zoo) = $q->dequeue_dontwait;
    my ($iffoo,$ifbar,$ifzoo) = $q->dequeue_keep;
    my $left = $q->pending;

=head1 説明

                    *** A note of CAUTION ***

 This module only functions on Perl versions 5.8.0-RC3 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-RC3 or without
 threads enabled.

                    *************************

                    *** 注   意   書   き ***

 このモジュールはPerl 5.8.0-RC3とそれ以降でのみ機能する。
 かつ、-Dusethreadsでスレッドが有効になっている場合だけである。
 5.8.0-RC3より前のバージョン、あるいはスレッド機能が有効になって
 いない場合は、利用できない。

                    *************************

A queue, as implemented by C<Thread::Queue::Any> is a thread-safe 
data structure that inherits from C<Thread::Queue>.  But unlike the
standard C<Thread::Queue>, you can pass (a reference to) any data
structure to the queue.

C<Thread::Queue::Any>によって実装されるキューは、スレッドセーフな
データ構造であり、C<Thread::Queue>を継承している。しかし、標準的な
C<Thread::Queue>と違って、どんなデータ構造（へのリファレンス）でも
このキューに渡すことができる。

Apart from the fact that the parameters to C<enqueue> are considered to be
a set that needs to be enqueued together and that C<dequeue> returns all of
the parameters that were enqueued together, this module is a drop-in
replacement for C<Thread::Queue> in every other aspect.

C<enqueue>に渡すパラメータは一度にenqueueされてしまうセットであることと、
C<dequeue>はその一度にenqueueしたパラメータを全て返すという事実を別にして、
このモジュールは多くの面でC<Thread::Queue>の差し込み式の代替となる。

Any number of threads can safely add elements to the end of the list, or
remove elements from the head of the list. (Queues don't permit adding or
removing elements from the middle of the list).

任意の数のスレッドが、安全にリストの最後に要素を加えたり、あるいは、
リストの先頭から要素を取り除ける（キューはリストの途中に要素を加えたり
取り除いたりはできない）。

=head1 クラスメソッド

=head2 new

 $queue = Thread::Queue::Any->new;

The C<new> function creates a new empty queue.

C<new>関数は新たな空キューを生成する。

=head1 オブジェクトメソッド

=head2 enqueue LIST

 $queue->enqueue( 'string',$scalar,[],{} );

The C<enqueue> method adds a reference to all the specified parameters on to
the end of the queue.  The queue will grow as needed.

C<enqueue>メソッドは、キューの最後尾に指定した全パラメータへの
リファレンスを加える。キューは必要に応じて成長する。

=head2 dequeue

 ($string,$scalar,$listref,$hashref) = $queue->dequeue;

The C<dequeue> method removes a reference from the head of the queue,
dereferences it and returns the resulting values.  If the queue is currently
empty, C<dequeue> will block the thread until another thread C<enqueue>s.

C<dequeue>メソッドは、キューの先頭からリファレンスを一つ取り除き、
デリファレンスしてその結果の値を返す。もしその時キューが空なら、他の
スレッドがC<enqueue>するまでC<dequeue>はブロックする。

=head2 dequeue_dontwait

 ($string,$scalar,$listref,$hashref) = $queue->dequeue_dontwait;

The C<dequeue_dontwait> method, like the C<dequeue> method, removes a
reference from the head of the queue, dereferences it and returns the
resulting values.  Unlike C<dequeue>, though, C<dequeue_dontwait> won't wait
if the queue is empty, instead returning an empty list if the queue is empty.

C<dequeue_dontwait>メソッドは、C<dequeue>と同様、キューの先頭から一つ
リファレンスを取り除き、デリファレンスしてその結果の値を返す。しかし、
C<dequeue>と違って、C<dequeue_dontwait>はキューが空でも待ちに入らない。
その代わりに空リストが返される。

For compatibility with L<Thread::Queue>, the name "dequeue_nb" is available
as a synonym for this method.

L<Thread::Queue>との互換性のため、"dequeue_nb"がこのメソッドの同義語として
利用可能。

=head2 dequeue_keep

 ($string,$scalar,$listref,$hashref) = $queue->dequeue_keep;

The C<dequeue_keep> method, like the C<dequeue_dontwait> method, takes a
reference from the head of the queue, dereferences it and returns the
resulting values.  Unlike C<dequeue_dontwait>, though, the C<dequeue_keep>
B<won't remove> the set from the queue.  It can therefore be used to test if
the next set to be returned from the queue with C<dequeue> or
C<dequeue_dontwait> will have a specific value.

C<dequeue_keep>メソッドは、C<dequeue_dontwait>同様、キューの先頭から
リファレンスを一つ取り、デリファレンスしてその結果の値を返す。
しかしC<dequeue_dontwait>と違って、C<dequeue_keep>はキューからそのセットを
B<取り除かない>。よって、C<dequeue_dontwait>が特定の値を持つことになるか
どうかテストするのに使える。

=head2 pending

 $pending = $queue->pending;

The C<pending> method returns the number of items still in the queue.

C<pending>メソッドはまだキューに残っているアイテムの数を返す。

=head1 必要なモジュール

 Storable (バージョンはどれでも)
 Thread::Queue (バージョンはどれでも)

=head1 警告

Passing unshared values between threads is accomplished by serializing the
specified values using C<Storable> when enqueuing and de-serializing the queued
value on dequeuing.  This allows for great flexibility at the expense of more
CPU usage.  It also limits what can be passed, as e.g. code references can
B<not> be serialized and therefore not be passed.

スレッド間で非共有な値を渡す処理は、C<Storable>を利用して指定の値を
シリアライズすることによって達成している（これを利用するのはenqueue時と、
キューされた値をdequeueする際のデシリアライズの時）。これは、より多くの
CPU消費を犠牲にする代わりに、大きな柔軟性を考慮したためである。
また、キューに渡せるものにも制限がある。例えば、コードリファレンスは
シリアライズ化B<できない>ので、渡すことはできない。

=head1 作者

Elizabeth Mattijsen, <liz@dijkmat.nl>.

Please report bugs to <perlbugs@dijkmat.nl>.

=head1 著作権

Copyright (c) 2002-2003 Elizabeth Mattijsen <liz@dijkmat.nl>. 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<threads>, L<threads::shared>, L<Thread::Queue>, L<Storable>.