hiSyncQue (OtsuLibrary)

java.lang.Object
- otsu.hiNote.hiSyncQue<T>

public class hiSyncQue<T>
extends Object

同期QUEUE.

スレッドからスレッドにデータを引き渡すQUEUEです。
生産者側、消費者側とも複数のスレッドであることが許されます。
生産者側が投じたデータ順、消費者側が待ち受けを開始した順はともに守られます。

put(T)でデータをセットしget()でデータを取得します。
データがセットされていない状態でget()するとデータがput()されるまでブロックします。

setLimit(int)QUEUEの最大サイズを指定すると QUEUEサイズがそれを超えないよう put()側でブロックさせることができます。
put()側でブロックしている状態でget()があると、put() 側のブロックは解けます。

次のように使用できます。

import otsu.hiNote.hiSyncQue;
class data {
   int    id;String text;
   data(int id_,String text_){id=id_;text=text_;}
   }
class Producer extends Thread{ // 生産者側
   hiSyncQue<data> que;
   Producer(hiSyncQue<data> que_){ que= que_; }
   public void run(){
      try{
         for(int n=10;n>=0;--n){
            que.put(new data(n,"data:"+n)); // 送る
            System.out.println("put:"+n);
            }
         que.set_return_null_when_empty(true);// データ終了
         }
      catch(Exception e){e.printStackTrace(hiU.err);}
      }
   }
class Consumer extends Thread{ // 消費者側
   hiSyncQue<data> que;
   Consumer(hiSyncQue<data> que_){ que= que_; }
   public void run(){
      try{
         data d;
         while( (d=que.get())!=null ){ // 受ける
            System.out.println("get:"+d.id+" "+d.text);
            Thread.sleep(150);// 150 milli-sec. sleep
            }
         }
      catch(Exception e){e.printStackTrace(hiU.err);}
      }
   }
public class MyClass {
   final static boolean D=true;
   public static void main(String args[]){
      try{
         hiSyncQue<data> que     = new hiSyncQue<data>(5);// queueのサイズ５
         Producer        producer= new Producer(que);
         Consumer        consumer= new Consumer(que);
         producer.start();
         consumer.start();
         }
      catch(Exception e){
         e.printStackTrace(hiU.err);
         System.exit(1);
         }
      }
   }

これを動かした結果は次のようになります。消費者側の速度が遅いため、生産者側にqueueサイズによる調整が入ることが分かります。

put:10
get:10 data:10
put:9
put:8
put:7
put:6
put:5
get:9 data:9
put:4
get:8 data:8
put:3
get:7 data:7
put:2
get:6 data:6
put:1
get:5 data:5
put:0
get:4 data:4
get:3 data:3
get:2 data:2
get:1 data:1
get:0 data:0

最大数を超える場合デフォルトではputがブロックしますが、次の設定を行うこともできます。

先頭を削除し、追加	:`remove_top_at_limit()`
最後を削除し、追加	:`remove_last_at_limit()`
追加せず廃棄	:`abandon_at_limit()`

一つのSyncQueに対し複数スレッドからputし、複数スレッドがgetすることも可能です。

複数のスレッドからget()が出ている場合、先に発行されたget()から順に値が渡されます。

set_return_null_when_emptyを発行するとデータが空になるとget()は待ちに入らずnullを返します。穏やかに消費スレッドを終了させることができます。
例えば次のコードでは予め起動した5個のデータ処理スレッドは、queにデータが投入されるとそれらの処理をします。生産者側がset_return_null_when_emptyを発行した後は、データがなくなり次第速やかにデータ処理スレッドは終了します。

// 消費者側スレッド
class Consumer extends Thread {
   hiSyncQue<MyData> que;
   public Consumer(hiSyncQue<MyData> que_){que=que_;}
   public void run(){
      MyData data;
      while( (data=que.get())!=null ){ // nullなら終了
         // data処理
         }
      }
   }
// 生産者側
   hiSyncQue<MyData> que=new hiSyncQue<MyData>();
   // 処理スレッドを起動
   for(int n=0;n<5;++n){
      (new Consumer(que)).start();
      }
   // データセット
   for(MyData data:dataList){
      que.put(data);
      }
   // データがなくなったらgetがnullを返す指定
   que.set_return_null_when_empty(true);

複数のget()あるいはput()がブロックされている状態で #clean(true); を発行すると全てのブロックが解除されます。

LinkedBlockingDequeとArrayBlockingQueue

hiSyncQueはjavaの初期に開発されたものです。前身はジェネリック機構すらない時代に作成されました。
その後javaの標準ライブラリに同様のクラス

などが作成されました。hiSyncQueを置き換える場合の注意点を説明します。

２つのクラスには大きな特徴があります。

LinkedBlockingDeque	:消費側の順序が保障されない
ArrayBlockingQueue	:最大サイズを指定する必要がある。要求を先頭に追加はできない

この制限が問題ない場合hiSyncQueの代用はできます。

基本メソッドの対応

メソッドの対応は次のようになります。

hiSyncQue	LinkedBlockingDeque	LinkedBlockingQueue	ArrayBlockingQueue	補足
put(E)	put(E)	put(E)	put(E)	QUEUEの最後へ追加します。
get()	take()	take()	take()	QUEUEの先頭から取得します。データがない場合待ちになります。 take()は割り込みExceptionを投げますので次のようなコードを書く必要があります。 E e; try{ e=que.take(); } catch(Exception ex){ e=null; } // eを使う LinkedBlockingDeque,LinkedBlockingQueueではtakeの戻り順は保障されません。 ArrayBlockingQueueは起動時にfair指定をした場合、takeの戻り順はtakeの発行順となります。
putTop(E)	putFirst(E)	---	---	QUEUEの先頭へ追加します。
tryGet()	poll()	poll()	poll()	QUEUEの先頭のデータを取得します。データがない場合nullが返ります。

穏やかな終了

hiSynqQueで用意されている「穏やかな終了」はありません。

hiSyncQueでは、複数の消費者が待っているところに、生産者が全生産終了時に hiSyncQuereturn_null_when_emptyフラグを立てるとそれらが全て消費されると、消費者側のget()がnullを返します。これにより穏やかな終了が可能となります。

// 消費者側スレッド
class Consumer extends Thread {
   hiSyncQue<MyData> que;
   public Consumer(hiSyncQue<MyData> que_){que=que_;}
   public void run(){
      MyData data;
      while( (data=que.get())!=null ){ // nullなら終了
         // data処理
         }
      }
   }
// 生産者側
   hiSyncQue<MyData> que=new hiSyncQue<MyData>();
   // 処理スレッドを起動
   for(int n=0;n<5;++n){
      (new Consumer(que)).start();
      }
   // データセット
   for(MyData data:dataList){
      que.put(data);
      }
   // データがなくなったらgetがnullを返す指定
   que.set_return_null_when_empty(true);

コンストラクタのサマリー

コンストラクタ
コンストラクタと説明
`hiSyncQue()` QUEUEサイズ限定なしの同期QUEUEを作成する.
`hiSyncQue(int limit_)` 予めQUEUEの最大サイズを指定する
`hiSyncQue(int limit_, String name_)` 予めQUEUEの最大サイズを指定する
`hiSyncQue(String name_)` QUEUEサイズ限定なしの名前付き同期QUEUEを作成する.

メソッドのサマリー

すべてのメソッドインスタンス・メソッド concreteメソッド
修飾子とタイプ	メソッドと説明
`void`	`abandon_at_limit()` 最大数を超える場合,追加せず廃棄する
`void`	`block_at_limit()` 最大数を超える場合,ブロックする(デフォルト)
`ArrayList<T>`	`clean(boolean wakeup_)` QUEUEに溜まっているデータを破棄する.
`boolean`	`detachData(ArrayList<T> data_)` QUEUEから指定データを取り外す.
`boolean`	`detachData(T data_)` QUEUEから指定データを取り外す.
`T`	`get()` QUEUEのデータを取り出す.
`T`	`get(long timeout_)` QUEUEのデータを取り出す.タイムアウト指定あり(試験中) QUEUEが空の場合ブロックします。
`T`	`getFirst()`
`int`	`getLimit()` QUEUEに溜められる最大数を得る.
`ArrayList<T>`	`getList()` QUEUEに溜まっているデータリストを得る.
`String`	`getName()` queueの名前を取得する.
`ArrayList<Long>`	`getWaitingThreadIdList()` 待ち状態のスレッドのidリストを得る呼び出し時点での待ち状態のスレッドのidのリスト。
`boolean`	`put(T obj_)` QUEUEの最後にデータを追加する.
`boolean`	`put(T obj_, int timeout_)` QUEUEの最後にデータを追加する；タイムアウトあり(試験中).
`boolean`	`putTop(T obj_)` QUEUEの先頭にデータを追加する
`boolean`	`putTop(T obj_, int timeout_)` QUEUEの先頭にデータを追加する；タイムアウトあり（試験中)
`void`	`remove_last_at_limit()` 最大数を超える場合,最後を削除する
`void`	`remove_top_at_limit()` 最大数を超える場合,先頭を削除する
`void`	`restart(boolean return_null_)` clean(true)で停止状態にしたものを、再使用可能にします。
`void`	`set_return_null_when_empty(boolean return_null_)` QUEUEが空の時、get()でwaitせずnullを返す指定.
`void`	`setLimit(int limit_)` QUEUEに溜められる最大数を設定する.
`void`	`setName(String name_)` queueにデバッグ用の名前を設定する.
`int`	`size()` QUEUEに溜まっているデータ数を得る.
`T`	`tryGet()` QUEUEのデータを取り出す.
`T`	`waitFor()` QUEUEのデータを取り出す.
`T`	`waitFor(long timeout_)` QUEUEのデータを取り出す.
`boolean`	`wakeupThread(ArrayList<Long> tids_)` 待ち状態のスレッドの待ちを解く（未).
`boolean`	`wakeupThread(long tid_)` 待ち状態のスレッドの待ちを解く（未).

クラスから継承されたメソッド java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- コンストラクタの詳細
  - hiSyncQue
```
public hiSyncQue()
```
    QUEUEサイズ限定なしの同期QUEUEを作成する.
    QUEUEの最大サイズは後からsetLimit(int)で設定することができます。
  - hiSyncQue
```
public hiSyncQue(String name_)
```
    QUEUEサイズ限定なしの名前付き同期QUEUEを作成する.
    名前は主にデバッグ用に使います。
    QUEUEの最大サイズは後からsetLimit(int)で設定することができます。
    
    パラメータ:
    
    name_ - 名前
  - hiSyncQue
```
public hiSyncQue(int limit_)
```
    予めQUEUEの最大サイズを指定する
    
    パラメータ:
    
    limit_ - QUEUEの最大サイズ
  - hiSyncQue
```
public hiSyncQue(int limit_,
                 String name_)
```
    予めQUEUEの最大サイズを指定する
    
    パラメータ:
    
    limit_ - QUEUEの最大サイズ
    
    name_ - 名前
- メソッドの詳細
  - setName
```
public void setName(String name_)
```
    queueにデバッグ用の名前を設定する.
    
    パラメータ:
    
    name_ - 名前
  - getName
```
public String getName()
```
    queueの名前を取得する.
    
    戻り値:
    
    名前
  - put
```
public boolean put(T obj_)
```
    QUEUEの最後にデータを追加する.
    
    パラメータ:
    
    obj_ - QUEUEに追加するデータオブジェクト
    
    戻り値:
    
    true:データオブジェクトが追加された。false:データオブジェクトは追加されなかった
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - put
```
public boolean put(T obj_,
                   int timeout_)
```
    QUEUEの最後にデータを追加する；タイムアウトあり(試験中).
    
    パラメータ:
    
    obj_ - QUEUEに追加するデータオブジェクト
    
    timeout_ - タイムアウト・ミリ秒
    
    戻り値:
    
    true:データオブジェクトが追加された。false:データオブジェクトは追加されなかった
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - putTop
```
public boolean putTop(T obj_)
```
    QUEUEの先頭にデータを追加する
    
    パラメータ:
    
    obj_ - QUEUEに追加するデータオブジェクト
    
    戻り値:
    
    true:追加した、false:サイズ制限で追加しなかった
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - putTop
```
public boolean putTop(T obj_,
                      int timeout_)
```
    QUEUEの先頭にデータを追加する；タイムアウトあり（試験中)
    
    パラメータ:
    
    obj_ - QUEUEに追加するオブジェクト
    
    timeout_ - タイムアウト・ミリ秒
    
    戻り値:
    
    true:追加した、false:サイズ制限で追加しなかった
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - get
```
public T get()
```
    QUEUEのデータを取り出す.
    QUEUEが空の場合ブロックします。clean()が発行された場合はnullが戻ります。
    通常ひとつのQUEUEに複数のスレッドからget()が出ている場合、先に出たget() から順にブロックが解けます。
    
    戻り値:
    
    取り出したデータ。
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - getFirst
```
public T getFirst()
```
  - waitFor
```
public T waitFor()
```
    QUEUEのデータを取り出す. get()と同じです。
    
    戻り値:
    
    QUEUEから取り出したデータ
  - tryGet
```
public T tryGet()
```
    QUEUEのデータを取り出す.
    QUEUEが空の場合ブロックせずnullを返します。
    
    戻り値:
    
    取り出したデータ。
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - get
```
public T get(long timeout_)
```
    QUEUEのデータを取り出す.タイムアウト指定あり(試験中)
    QUEUEが空の場合ブロックします。clean()が発行された場合はnullが戻ります。
    ひとつのQUEUEに複数のスレッドからget()が出ている場合、先に出たget() から順にブロックが解けます。
    タイムアウトした場合nullが返ります。複数のスレッドでgetを出す場合各get毎に異なるタイムアウトが設定できます。
    
    パラメータ:
    
    timeout_ - タイムアウト時間をミリ秒で指定
    
    戻り値:
    
    取り出したデータ。タイムアウトの場合null
    
    例外:
    
    RuntimeException - IllegalMonitorStateExceptionまたは InterruptedExceptionをcauseとして持つ。
  - waitFor
```
public T waitFor(long timeout_)
```
    QUEUEのデータを取り出す. get()と同じです。
    
    パラメータ:
    
    timeout_ - タイムアウト・ミリ秒
    
    戻り値:
    
    データ
  - clean
```
public ArrayList<T> clean(boolean wakeup_)
```
    QUEUEに溜まっているデータを破棄する.
    QUEUE内のデータを廃棄します。
    
    引数にtrueを設定すると、get(),put()の待ち状態は全て解除され、このQUEUEは使用できなくなります。
    使用可能とするにはrestartを呼びます。
    
    パラメータ:
    
    wakeup_ - get()のブロックを解除する。get()側にはnullが通知される。 put()のブロックも解除される。
    
    戻り値:
    
    溜まっていたデータ
  - restart
```
public void restart(boolean return_null_)
```
    clean(true)で停止状態にしたものを、再使用可能にします。
    
    パラメータ:
    
    return_null_ - trueを指定するとQUEUEが空の時nullリターンします。
  - set_return_null_when_empty
```
public void set_return_null_when_empty(boolean return_null_)
```
    QUEUEが空の時、get()でwaitせずnullを返す指定.
    送り手側(put側)で一連のデータが終わったことをこの指定で示せば、受け側(get側) は溜まっているデータを全て受け取った後はnullを受け取り、終わりを知ることができます。
    
    set_return_null_when_empty(true)を発行すると、 set_return_null_when_empty(false)を発行するまで、put()は無処理となります。
    
    パラメータ:
    
    return_null_ - trueを指定するとQUEUEが空の時nullリターンします。
  - size
```
public int size()
```
    QUEUEに溜まっているデータ数を得る.
    
    戻り値:
    
    QUEUEに溜まっているデータ数
  - setLimit
```
public void setLimit(int limit_)
```
    QUEUEに溜められる最大数を設定する.
    QUEUEに溜まったデータ数最大数に達すると put()はブロックします。
    0は設定無しを表します。
    
    パラメータ:
    
    limit_ - QUEUEに溜められるオブジェクトの最大数
  - getLimit
```
public int getLimit()
```
    QUEUEに溜められる最大数を得る.
    
    戻り値:
    
    QUEUEに溜められるオブジェクトの最大数
  - block_at_limit
```
public void block_at_limit()
```
    最大数を超える場合,ブロックする(デフォルト)
  - remove_top_at_limit
```
public void remove_top_at_limit()
```
    最大数を超える場合,先頭を削除する
  - remove_last_at_limit
```
public void remove_last_at_limit()
```
    最大数を超える場合,最後を削除する
  - abandon_at_limit
```
public void abandon_at_limit()
```
    最大数を超える場合,追加せず廃棄する
  - getList
```
public ArrayList<T> getList()
```
    QUEUEに溜まっているデータリストを得る.
    呼び出し時点でQUEUEに溜まっているデータのリストを得ます。
    データオブジェクトは溜まっているオブジェクトそのものですが、リストは応答ように作られたものです。
    リストに変更を加えてもQUEUEには影響はありません。
    
    戻り値:
    
    QUEUEに溜まっているデータリスト
  - detachData
```
public boolean detachData(T data_)
```
    QUEUEから指定データを取り外す.
    指定のデータインスタンスがQUEUEにある場合取り外します。
    指定するのはQUEUEに入れたデータそのもので、equalsなどによる比較は行いません。
    
    パラメータ:
    
    data_ - 取り外すデータ。
    
    戻り値:
    
    true:取り外した,false:QUEUEにはなかった
  - detachData
```
public boolean detachData(ArrayList<T> data_)
```
    QUEUEから指定データを取り外す.
    指定のデータインスタンスがQUEUEにある場合取り外します。
    指定するのはQUEUEに入れたデータそのもので、equalsなどによる比較は行いません。
    
    パラメータ:
    
    data_ - 取り外すデータ。
    
    戻り値:
    
    true:取り外した,false:QUEUEにはなかった
  - getWaitingThreadIdList
```
public ArrayList<Long> getWaitingThreadIdList()
```
    待ち状態のスレッドのidリストを得る
    呼び出し時点での待ち状態のスレッドのidのリスト。
    リストは応答用に作られたものです。
    リストに変更を加えてもQUEUEには影響はありません。
    
    戻り値:
    
    待ち状態のスレッドのidのリスト
  - wakeupThread
```
public boolean wakeupThread(long tid_)
```
    待ち状態のスレッドの待ちを解く（未).
    指定スレッドidのスレッドが待ち状態の場合、待ち状態を解きます。
    解かれた側のスレッドのget()はnullが返ります。
    
    パラメータ:
    
    tid_ - 待ちを解くスレッドid
    
    戻り値:
    
    true:待ち状態を解いた、false:指定スレッドは待ち状態ではなかった
  - wakeupThread
```
public boolean wakeupThread(ArrayList<Long> tids_)
```
    待ち状態のスレッドの待ちを解く（未).
    指定スレッドidのスレッドが待ち状態の場合、待ち状態を解きます。
    解かれた側のスレッドのget()はnullが返ります。
    
    パラメータ:
    
    tids_ - 待ちを解くスレッドid
    
    戻り値:
    
    true:待ち状態を解いた、false:指定スレッドは待ち状態ではなかった

クラス hiSyncQue<T>

コンストラクタのサマリー

メソッドのサマリー

クラスから継承されたメソッド java.lang.Object

コンストラクタの詳細

hiSyncQue

hiSyncQue

hiSyncQue

hiSyncQue

メソッドの詳細

setName

getName

put

put

putTop

putTop

get

getFirst

waitFor

tryGet

get

waitFor

clean

restart

set_return_null_when_empty

size

setLimit

getLimit

block_at_limit

remove_top_at_limit

remove_last_at_limit

abandon_at_limit

getList

detachData

detachData

getWaitingThreadIdList

wakeupThread

wakeupThread