名称

rpoll - ファイル記述子とタイマのためのコールバック関数

書式

# include <rpoll.h>

typedef void (*poll_f)(int fd , int mask , void *arg );

typedef void (*timer_f)(int tid , void *arg );

int poll_register(int fd , poll_f func , void *arg , int mask );

void poll_unregister(int handle );

int poll_start_timer(u_int msecs , int repeat , timer_f func , void *arg );

void poll_stop_timer(int handle );

int poll_start_utimer(unsigned long long usecs , int repeat , timer_f func , void *arg );

void poll_dispatch(int wait );

解説

多くのプログラムは、同時にいくつかのファイル記述子で読み込む必要があります。通常これらのプログラムでは、 select(3c) または poll(2) の 1 つが使用されています。これらの呼び出しが、使用するためにどんなに出来が悪くても、これらの呼び出しの 1 つの使用法は、たぶん他のシステムに移植可能ではありません - すべてのシステムが両方の呼び出しをサポートするわけではありません。

rpoll(l) ファミリ関数は、これらの制限を打開するように設計されています。それは、イベント駆動のプログラミングのよく知られていて理解されている技術 (テクニック) をサポートし、さらに select(3c) と poll(2) もまたタイマをサポートします。

ファイル記述子または各タイマイベントにおける各イベントはユーザ定義コールバック関数への呼び出しに変換されます。これらの関数は、登録される必要があります。ファイル記述子は poll_register に登録されます。 fd はウォッチする (見張る) ファイル記述子で、 mask はイベントマスクです。それは、ファイル記述子の入力が可能になるとき、知らされる POLL_IN、出力が可能になるとき、知らされる POLL_OUT、または例外的な状態か起こったとき、知らされる POLL_EXCEPT の任意の組み合わせです。例外的な状態の例は緊急のデータの到着です。 (ファイルの終り状態は、POLL_IN を通して知らされることに注意してください)。 func は呼び出されるユーザ関数です、そして、 arg はこの関数にユーザによって供給される引数です。コールバック関数は、ファイル記述子、(登録で供給されたセットからの) 実際のイベントを記述マスク、とユーザ引数で呼び出されます。 poll_register はファイル記述子の登録を取り消すために後で使用される、ハンドルを返します。ファイル記述子は、関数、ユーザ引数、または両方が poll_register の呼び出しで異なるなら、何度も登録されるかもしれません。 func と arg が同じであるなら、新しい登録を行わす、代わりに、登録のイベントマスクは新しいマスクを反映するように変更されます。

登録済みのファイル記述子は、 poll_register によって返されるハンドルで poll_unregister を呼び出して登録を取り消すことができます。

タイマは poll_start_timer または poll_start_utimer で作成されます。 msecs は、タイマイベントが生成された後の poll_start_timer のミリ秒の数ですが、一方 usecs は、 poll_start_utimer のマイクロ秒の数です。関数が、 poll(2) システムコールを使用するなら、 usecs は、ミリ秒に丸められ、 poll_start_timer が呼び出されます。 repeat は、(0 なら) 1 つの短い振る舞いか、または (0 でないなら) 繰り返し可能なタイマを選択します。 1 つの短いタイマは期限が切れた後に自動的に登録が取り消されます。 func はタイマ ID とユーザが供給した arg で呼び出されるユーザ関数です。 poll_start_timer と poll_start_utimer は、 poll_stop_timer でタイマをキャンセルするために使用される、タイマ ID を返します。 1 つの短いタイマは、まだ開始していない場合にだけ取り消されるべきです。

poll_dispatch は実際にイベントをディスパッチするために呼び出されなければなりません。 wait はポーリングが終了する場合のみ、0 になるべきフラグです。この場合、登録済みのファイル記述子とタイマをポーリングした後に、関数は戻ります。 wait が 0 でないなら、 poll_dispatch はイベント起こるまでウェート (wait) します。すべてのイベントがディスパッチされ (すなわち、コールバック関数が呼び出される)、 poll_dispatch は戻ります。

典型的な使用は次の通りです:

関連項目

poll(2), select(3C)

戻り値

poll_register , poll_start_timer と poll_start_utimer は、ファイル記述子を登録を解除するか、またはタイマをキャンセルするために使用されるハンドルに返します。

両方の関数と poll_dispatch は xrealloc(l) を呼び出し、 panic(l) で終るかもしれません。

エラー

システムコールまたはメモリ割り付けのエラーは、致命的であり、 panic(l) を呼び出すことによって対処されます。 1 つの例外は select(3c) または poll_dispatch での poll(2) から EINTR が返されることです。この場合、 poll_dispatch は単に戻ります。

バグ

コールバック関数での poll_start_timer と poll_stop_timer の不明りょうなシーケンスは、たぶんコードを中断するかもしれません。

POLL_EXCEPT のセマンティックス (意味) は明確ではありません。

作者

Hartmut Brandt, harti@freebsd.org