transworker
transworker - WebWorkerをメソッド呼び出し感覚で利用するモジュール
photo credit: Pallet
via photopin
(license)
概要
TransWorkerは WebWorkerを手軽に扱えるようにする モジュールです。
ワーカースレッドで動かしたい処理を、クラスのインスタンスメソッドとして定義して、 メインスレッド側からワーカースレッド側のメソッドを呼び出せるようにしています。
各メソッドの戻り値はメインスレッド側で呼び出し時に指定したコールバック関数に返されます。
ワーカースレッド側から通知メッセージを発行することも可能です。
利用方法
バンドラーを利用する場合(オススメ)
npm install --save transworker
const TransWorker = ;
HTMLから直接読み込む方法
バンドラーを使用しない場合は、ビルド済みの transworker.js を読み込みます。 TransWorker クラスが利用可能です。
ローカルファイルを読み込む
$ git clone https://github.com/takamin/transworker.git$ cd transworker$ npm install$ npm run build # ./transworker.js が生成されます。
・・・・・・
GitHub.Ioのスクリプトを読み込む(非推奨)
本モジュールの GitHub Pages のビルド済みファイルも利用可能ですが、 更新の制御ができませんので継続的な利用にはお勧めしません。
・・・・・・
SharedWorker を使ったサンプル
ワーカースレッドで延々と素数を見つけてメインスレッドへ通知するサンプルです。
sample/prime/index.html
HTMLファイルです。表示した時から延々と素数を見つけて画面に表示します。 あまり長時間開きっぱなしにするとページが長くなりすぎるのでよくないです。
以下のSCRIPTで読み込んでいる app-bundle.js
は、次の app.js
をバンドルしたものです。
<!doctype HTML>Find Prime Numbersspan { display:inline-block; padding:10px; margin:2px; }.label { width:120px; text-align:center; background-color:silver; border: solid gray 1px; }Find Prime Numbers
sample/prime/app.js
メインスレッド側のスクリプトです。 TransWorkerを使ってPrimeクラスのSharedWorkerを作成し、 素数の通知を購読し、処理を開始します。
const TransWorker = ;const Prime = ; const result = document; const primeWorker = TransWorker; primeWorker; primeWorkerstart;
sample/prime/prime.js
TransWorkerで利用する前提の素数を見つけるクラスです。 ワーカーコンテキストで生成されて、TransWorkerを介して各メソッドが呼び出されます。
素数をメインスレッドへ知らせるために利用している
_transworker
フィールドはTransWorkerから注入されたものです。
※ メインスレッドではメソッドのインターフェースのみが利用されます。
{ thisprimes = ; thistid = null;} Primeprototype { //SharedWorkerとして実行される場合は既に実行されている //可能性がある ifthistid != null console; return; let prime = 1; thistid = ;}; Primeprototype { for;; n++; ifthis return n; }; Primeprototype { forconst prime of thisprimes ifn % prime == 0 return false; return true;}; moduleexports = Prime;
sample/prime/prime-worker.js
メインスレッド側のTransWorkerのインスタンスから読み込まれる ワーカーコンテキストのスクリプトです。
ここではSharedWorkerとして動作するPrimeクラスのTransWorkerを生成しています。
const TransWorker = ;const Prime = ;TransWorker;
TransWorkerオブジェクトの生成
メインスレッド側で、TransWorkerのインスタンスを生成するには、 ワーカースレッドで動作するスクリプトのURL と、 そこで動作させようとしている クラスの定義(コンストラクタ) を与えます。
ワーカースレッドのスクリプトでも、同じクラスのインスタンスを与えて、 TransWorkerオブジェクトを生成しておきます。
メソッド呼び出しをスレッド間のメッセージ送受信に変換
メインスレッド側のTransWorkerは、与えられたクラスに定義されているインスタンスメソッドのラッパー関数を TransWorkerオブジェクト内に生成 します。 これらラッパー関数は、ワーカースレッドへメソッド呼び出しのためのメッセージを送信します。
ワーカースレッドのTransWorkerオブジェクトは、メインスレッドからこのメッセージを受信すると、 インスタンスメソッドを呼び出します。戻り値はメインスレッドへメッセージにより返されます。
メインスレッド側インスタンス生成
TransWorker.createInterface(urlDerivedWorker, clientCtor, options)
TransWorker.createInvoker(urlDerivedWorker, clientCtor, thisObject, notifyHandlers) - deprecated
TransWorker.createSharedInvoker(urlDerivedWorker, clientCtor, thisObject, notifyHandlers) - deprecated
メインスレッド側で利用できるTransWorkerオブジェクトを生成します。
createInvoker
はDedicatedWorkerを、createSharedInvoker
は、SharedWorkerを生成します。
createInterface
では、options引数によって、その種類を指定します。
PARAMETERS
- urlDerivedWorker:string - WebWorkerプロセスのURL。
- clientCtor:Function - クライアントクラスのコンストラクタ。
- options:TransWorker.Options - オプション。指定可能なキーを以下に示します。
- shared:boolean - 生成するWorkerの種類を指定します。
- false - (default) DedicatedWorker
- true - SharedWorker
- syncType:Function - 生成するラッパー関数の戻り値の受け取り方を指定します。
- TransWorker.SynTypeCallback - (default)コールバック関数の引数で戻り値を得る。
- TransWorker.SyncTypePromise - ラッパー関数から返されるPromiseオブジェクトの解決値として戻り値を得る。
- shared:boolean - 生成するWorkerの種類を指定します。
- thisObject:Any - (deprecated)通知を呼び出す場合のthisを指定する。
- notifyHandlers:Object - (deprecated)WebWorker側からの通知を受け取るハンドラーのマップ(キー:通知名、値:ハンドラー関数)。
DETAILS
TransWorkerのインスタンスを生成します。 インスタンスの生成と同時に第1引数で指定したスクリプトをワーカースレッドで実行します。 このスクリプトでは第2引数で指定したクラスのインスタンスを保持するワーカースレッド側のTransWorkerインスタンスが生成されている前提です。
メインスレッド側のTransWorkerインスタンスには、第二引数で指定したクラスの全インスタンスメソッドへのラッパー関数が実装されます。 各ラッパー関数はワーカースレッド側のTransWorkerインスタンスに対して、メソッド呼び出しのメッセージを発行しその戻り値を非同期で返します。
戻り値の受け取り方は、コールバック関数によるものとPromiseによるものの2つから選択できます。
createInterface
では、第3引数のoptions.syncTypeで選択します。
他の2つのメソッドはコールバック関数による受け取り方しか選択できません。
RETURNS
TransWorkerのインスタンスを返します。
ワーカースレッドからの通知を受け取る
transworker.subscribe(notificationName, handler)
ワーカースレッドからの通知を購読します。
PARAMETERS
- notificationName - 通知の名称。
- handler - 通知を処理するハンドラー。
DETAILS
既に購読している通知に新たなハンドラーは設定できません。
ワーカースレッド側インスタンス生成
TransWorker.createWorker(client)
TransWorker.createSharedWorker(client)
ワーカースレッドで動作するTransWorkerオブジェクトを生成します。
これは、メインスレッド側でのインスタンス生成時に、
引数 urlDerivedWorker
で指定するスクリプト中で使用する必要があります。
createWorker
はDedicatedWorker、
createSharedWorker
はSharedWorker
として実行されるためのインスタンスを生成します。
PARAMETERS
- client - ワーカースレッドで動作するクラスのインスタンス。
DETAILS
第一引数のインスタンスに、TransWorkerのインスタンスを保持させる
_transworker
というフィールドを追加します。
これを利用してTransWorkerのメソッドを呼び出せます。
RETURNS
ワーカースレッド側のTransWorkerインスタンスを返します。
ワーカーからメインスレッドへの通知
transworker.postNotify(name, parameter)
メインスレッド側のTransWorkerオブジェクトへ通知を送信します。
PARAMETERS
- name - 通知の名称。
- parameter - 通知に関連するパラメータ。
それぞれの内容は対象のクラスで独自に定義します。
LICENSE
MIT