From 051fc3e5ffeddaa356960d350336fa6f28269d71 Mon Sep 17 00:00:00 2001 From: okkez Date: Thu, 30 Sep 2010 18:58:34 +0900 Subject: [PATCH] update thread library document --- refm/api/src/thread.rd | 12 +++--- refm/api/src/thread/ConditionVariable | 22 +++++----- refm/api/src/thread/Mutex | 53 ++++++++++-------------- refm/api/src/thread/Queue | 72 ++++++++++++++++---------------- refm/api/src/thread/SizedQueue | 49 ++++++++++++++--------- 5 files changed, 103 insertions(+), 105 deletions(-) diff --git a/refm/api/src/thread.rd b/refm/api/src/thread.rd index 733b29b..a203b6e 100644 --- a/refm/api/src/thread.rd +++ b/refm/api/src/thread.rd @@ -1,8 +1,8 @@ -スレッド間キューや状態変数(condition variable)を提供するライブラリです。 +スレッド間キューや状態変数 (condition variable) を提供するライブラリです。 -このライブラリは[[c:Thread]]を拡張します．rubyインタプリタを -デバッグオプション付き([[m:$DEBUG]]を真)で実行したときには， -[[m:Thread.abort_on_exception]]をtrueにします +このライブラリは [[c:Thread]] を拡張します。rubyインタプリタを +デバッグオプション付き([[m:$DEBUG]]を真)で実行したときには、 +[[m:Thread.abort_on_exception]] を true にします。 #@#((-あらい: 2001-02-11 #@#$DEBUGが真の場合、rubyインタプリタの方で abort_on_exception を true にした @@ -12,8 +12,8 @@ = reopen Thread == Class Methods #@until 1.9.1 ---- Thread.exclusive { ... } -#@todo +--- exclusive { ... } -> object + #@# 1.9.1 以降は prelude.rb で定義されているので _builtin/Thread に移動しました。 ブロック実行中、Threadの切り替えを行いません。 diff --git a/refm/api/src/thread/ConditionVariable b/refm/api/src/thread/ConditionVariable index fb4d59c..aa6d36b 100644 --- a/refm/api/src/thread/ConditionVariable +++ b/refm/api/src/thread/ConditionVariable @@ -125,34 +125,32 @@ == Class Methods ---- ConditionVariable.new -#@todo +--- new -> ConditionVariable 状態変数を生成して返します。 == Instance Methods ---- broadcast -#@todo +--- broadcast -> [Thread] + 状態変数を待っているスレッドをすべて再開します。再開された スレッドは [[m:ConditionVariable#wait]] で指定した mutex のロックを試みます。 -実行待ちしていたスレッドの配列を返します。 +@return 実行待ちしていたスレッドの配列を返します。 + +--- signal -> Thread | nil ---- signal -#@todo 状態変数を待っているスレッドを1つ再開します。再開された スレッドは [[m:ConditionVariable#wait]] で指定した mutex のロックを試みます。 -状態を待っているスレッドがあった場合は、そのスレッドを返します。 -そうでなければ nil を返します。 +@return 状態を待っているスレッドがあった場合は、そのスレッドを返します。 + そうでなければ nil を返します。 + +--- wait(mutex) -> self ---- wait(mutex) -#@todo mutex のロックを解放し、カレントスレッドを停止します。 [[m:ConditionVariable#signal]]または、 [[m:ConditionVariable#broadcast]]で送られたシグナルを 受け取ると、mutexのロックを取得し、実行状態となります。 -self を返します。 diff --git a/refm/api/src/thread/Mutex b/refm/api/src/thread/Mutex index 51cdbcb..d96fd97 100644 --- a/refm/api/src/thread/Mutex +++ b/refm/api/src/thread/Mutex @@ -1,12 +1,11 @@ = class Mutex < Object Mutex(Mutal Exclusion = 相互排他ロック)は共有データを並行アクセスから保護する -ためにあります。Mutex の典型的な使い方は(mを -Mutexオブジェクトとします): +ためにあります。Mutex の典型的な使い方は(m を Mutex オブジェクトとします): m.lock begin - # mによって保護されたクリティカルセクション + # m によって保護されたクリティカルセクション ensure m.unlock end @@ -14,59 +13,48 @@ Mutex または、より簡単に m.synchronize { - # mによって保護されたクリティカルセクション + # m によって保護されたクリティカルセクション } == Class Methods ---- Mutex.new -#@todo +--- new -> Mutex 新しい mutex を生成して返します。 == Instance Methods #@until 1.9.1 ---- exclusive_unlock { ... } -#@todo +--- exclusive_unlock { ... } -> self | nil ロックを解放し、ロック待ちになっているスレッドを実行可能状態に した後、ブロックを実行します。 ブロックの実行が終了するまで、スレッドは切り替わりません。 -self がロックされていなければ nil を返します。そうでな -ければself を返します。 +@return self がロックされていなければ nil を返します。そうでなければself を返します。 #@end ---- lock -#@todo +--- lock -> self mutex オブジェクトをロックします。一度に一つのス レッドだけが mutex をロックできます。既にロックされている mutex に対してロックを行おうとしたスレッドは mutex のロックが解放さ れるまで、実行が停止されます。 -self を返します。 ---- locked? -#@todo +--- locked? -> bool mutex がロックされている時、真を返します。 ---- synchronize { ... } -#@todo -mutex をロックし、ブロックを実行します。実行後に必ず mutex のロッ -クを解放します。 +--- synchronize { ... } -> self ---- try_lock -#@todo -mutex をロックしようとして、ロックが成功した場合、真を返しま -す。ロックできなかった場合にはブロックせず偽を返します。 +mutex をロックし、ブロックを実行します。実行後に必ず mutex のロックを解放します。 ---- unlock -> self | nil +--- try_lock -> bool +mutex をロックしようとして、ロックが成功した場合、真を返します。 +ロックできなかった場合にはブロックせず偽を返します。 -mutex のロックを解放します。mutex のロック待ちになっていたスレッ -ドの実行は再開されます。 +--- unlock -> self | nil +mutex のロックを解放します。mutex のロック待ちになっていたスレッドの実行は再開されます。 -self がロックされていなければ nil を返します。そうでな -ければself を返します。 +@return self がロックされていなければ nil を返します。そうでなければself を返します。 例: @@ -93,9 +81,10 @@ Mutex #@since 1.9.1 --- sleep(timeout = nil) -> self -#@todo -Releases the lock and sleeps timeout seconds if it is given and -non-nil or forever. Raises ThreadError if mutex wasn't locked -by the current thread. +与えられた秒数の間スリープしてからロックを解放します。 + +@param timeout スリープする秒数を指定します。省略するとスリープし続けます。 + +@raise ThreadError 自身がカレントスレッドによってロックされていない場合に発生します。 #@end diff --git a/refm/api/src/thread/Queue b/refm/api/src/thread/Queue index cad08da..6d97b61 100644 --- a/refm/api/src/thread/Queue +++ b/refm/api/src/thread/Queue @@ -1,10 +1,10 @@ = class Queue < Object -Queueはスレッド間のFIFO(first in first out)の通信路です。ス -レッドが空のqueueを読み出そうとすると停止します。queueになんら +Queue はスレッド間の FIFO(first in first out) の通信路です。ス +レッドが空のキューを読み出そうとすると停止します。キューになんら かの情報が書き込まれると実行は再開されます。 -最大サイズが指定できるQueueのサブクラス[[c:SizedQueue]]も提供されています。 +最大サイズが指定できる Queue のサブクラス [[c:SizedQueue]] も提供されています。 === 例 @@ -33,40 +33,40 @@ Queue == Class Methods ---- new -#@todo -新しいqueueオブジェクトを生成します。 +--- new -> Queue + +新しいキューオブジェクトを生成します。 == Instance methods ---- clear -#@todo -queue を空にします。返り値は不定です。 - ---- empty? -#@todo -queueが空の時、真を返します。 - ---- length ---- size -#@todo -queueの長さを返します。 - ---- num_waiting -#@todo -queue を待っているスレッドの数を返します。 - ---- pop(non_block = false) ---- shift(non_block = false) ---- deq(non_block = false) -#@todo -queueからひとつ値を取り出します。queueが空の時、呼出元のスレッ -ドは停止します。non_block に true を与えると、 -queueが空の時に例外 [[c:ThreadError]] が発生します。 - ---- push(value) ---- <<(value) ---- enq(value) -#@todo -queue の値を追加します。待っているスレッドがいれば実行を再開 +--- clear -> () + +キューを空にします。返り値は不定です。 + +--- empty? -> bool + +キューが空の時、真を返します。 + +--- length -> Fixnum +--- size -> Fixnum + +キューの長さを返します。 + +--- num_waiting -> Fixnum + +キューを待っているスレッドの数を返します。 + +--- pop(non_block = false) -> object +--- shift(non_block = false) -> object +--- deq(non_block = false) -> object + +キューからひとつ値を取り出します。キューが空の時、呼出元のスレッドは停止します。 + +@param non_block true を与えると、キューが空の時に例外 [[c:ThreadError]] が発生します。 + +--- push(value) -> () +--- <<(value) -> () +--- enq(value) -> () + +キューの値を追加します。待っているスレッドがいれば実行を再開 させます。返り値は不定です。 diff --git a/refm/api/src/thread/SizedQueue b/refm/api/src/thread/SizedQueue index abfd7e7..a667be7 100644 --- a/refm/api/src/thread/SizedQueue +++ b/refm/api/src/thread/SizedQueue @@ -4,7 +4,7 @@ === 例 -[[ruby-list:283]]より。q をサイズ 1 の SizedQueue オブジェクトに +[[ruby-list:283]] より。q をサイズ 1 の SizedQueue オブジェクトに することによって、入力される行と出力される行が同じ順序になります。 q = [] にすると入力と違った順序で行が出力されます。 @@ -27,31 +27,42 @@ q = [] == Class Methods ---- new(max) -#@todo +--- new(max) -> SizedQueue SizedQueue オブジェクトを生成します。 -max は queue のサイズの最大値です。 + +@param max キューのサイズの最大値です。 == Instance Methods ---- max +--- max -> Fixnum +キューの最大サイズを返します。 + --- max=(n) -#@todo -queue の最大サイズを設定します。 +キューの最大サイズを設定します。 + +@param n キューの最大サイズを指定します。 + +--- push(obj) -> () +--- <<(obj) -> () +--- enq(obj) -> () + +キューに与えられたオブジェクトを追加します。 + +キューのサイズが [[m:SizedQueue#max]] に達している場合は、 +キューのサイズが [[m:SizedQueue#max]] より小さくなるまで他のスレッドに実行を譲ります。 +その後、キューに与えられたオブジェクトを追加します。 + +@param obj キューに追加したいオブジェクトを指定します。 ---- push(obj) -#@todo -queue に obj を追加します。 +@see [[m:Queue#push]] -queue のサイズが max に達している場合は、 -queue のサイズが max より小さくなるまで他のスレッドに実行を譲ります。その後、 -queue に obj を追加します。 +--- pop(non_block = false) -> object +--- shift(non_block = false) -> object +--- deq(non_block = false) -> object -あとは [[m:Queue#push]] と同じです。 +キューからひとつ値を取り出します。 +キューに push しようと待っているスレッドがあれば、実行を再開させます。 ---- pop -#@todo -queue からひとつ値を取り出します。 -queue に push しようと待っているスレッドがあれば、実行を再開させます。 +@param non_block true を与えると、キューが空の時に例外 [[c:ThreadError]] が発生します。 -あとは [[m:Queue#pop]] と同じです。 +@see [[m:Queue#pop]] -- 1.7.1