KQUEUE(9) | FreeBSD Kernel Developer's Manual | KQUEUE(9) |
名称
kqueue_add_filteropts, kqueue_del_filteropts, kqfd_register, knote_fdclose, knlist_init, knlist_init_mtx, knlist_init_rw_reader, knlist_add, knlist_remove, knlist_remove_inevent, knlist_empty, knlist_clear, knlist_delete, knlist_destroy, KNOTE_LOCKED, KNOTE_UNLOCKED — イベント配信サブシステム書式
#include < sys/event.h> int
kqueue_add_filteropts( int filt, struct filterops *filtops);
int
kqueue_del_filteropts( int filt);
int
kqfd_register( int fd, struct kevent *kev, struct thread *td, int waitok);
void
knote_fdclose( struct thread *td, int fd);
void
knlist_init( struct knlist *knl, void *lock, void (*kl_lock)(void *), void (*kl_unlock)(void *), int (*kl_locked)(void *));
void
knlist_init_mtx( struct knlist *knl, struct mtx *lock);
void
knlist_init_rw_reader( struct knlist *knl, struct rwlock *lock);
void
knlist_add( struct knlist *knl, struct knote *kn, int islocked);
void
knlist_remove( struct knlist *knl, struct knote *kn, int islocked);
void
knlist_remove_inevent( struct knlist *knl, struct knote *kn);
int
knlist_empty( struct knlist *knl);
void
knlist_clear( struct knlist *knl, int islocked);
void
knlist_delete( struct knlist *knl, struct thread *td, int islocked);
void
knlist_destroy( struct knlist *knl);
void
KNOTE_LOCKED( struct knlist *knl, long hint);
void
KNOTE_UNLOCKED( struct knlist *knl, long hint);
解説
関数 kqueue_add_filteropts() と kqueue_del_filteropts() は、フィルタタイプの追加と削除を可能にします。フィルタは、 EVFILT_* マクロによって静的に定義されます。関数 kqueue_add_filteropts() は、 filt を利用可能にします。 struct filterops には、次のメンバがあります:- f_isfd
- f_isfd が設定されるなら、 struct kevent の ident は、ファイル記述子を取ります。この場合、 f_attach に渡された knote は、ファイル記述子を表す struct file * で初期化された kn_fp メンバがあります。
- f_attach
- f_attach 関数は、 knote をオブジェクトにアタッチするとき、呼び出されます。メソッドは、 knlist_init() で初期化されたリストに knote を追加するために knlist_add() を呼び出すべきです。 knlist_add() への呼び出しは、オブジェクトがそれに関連している複数の knotes を持つことができる場合にだけ、必要です。 knlist_add() を呼び出すために knlist がないなら、関数 f_attach は、 knote で kn_status の KN_DETACHED ビットをクリアしなければなりません。関数は、成功すれば、0 を返し、オブジェクトが破壊されているか、または存在しないときのように、失敗すれば、適切なエラーを返します。 f_attach の間に、 kn_fops ポインタを異なったポインタに変更することは有効です。これは、 knote を処理するとき呼び出される f_event と f_detach 関数を変更します。
- f_detach
- f_detach 関数は、 knote が knlist_remove(), knlist_remove_inevent() または knlist_delete() への呼び出しによってまだにデタッチされていないなら、 knote をデタッチするために呼び出されます。リスト lock は、この関数が呼び出されるとき、保持されません。
- f_event
-
f_event 関数は、
knote の状態を更新するために呼び出されます。関数が 0 を返すなら、オブジェクトが起こされる準備ができていない (または、もはや準備ができない) と仮定されます。どれがトリガされるかを確認するために
knotes をスキャンするとき、
hint 引数は、0 になります。そうでなければ、
hint 引数は、
KNOTE_LOCKED または
KNOTE_UNLOCKED のいずれかの渡された値となります。
kn_data 値は、読み込みのために利用可能なバイト数、または書き込みのために利用可能なバッファ空間のような、現在の値を反映するために必要に応じて更新されるべきです。ノート (note) を、削除する必要があるなら、
knlist_remove_inevent() が、呼び出されなければなりません。関数
knlist_remove_inevent() は、リストからノートを削除し、
f_detach 関数は、呼び出されません、そして
knote は、イベントとして返されません。
ロックを f_event で獲得しては いけません。ロックが f_event で必要とされるなら、 knote が追加された knlist の kl_lock 関数で獲得しなければなりません。
関数 kqfd_register() は、kqueue ファイル記述子 fd で kevent を登録します。スリープが安全であるなら、 waitok が、設定されるべきです。
関数 knote_fdclose() は、 fd に関連しているすべての knotes を削除するために使用されます。いったん戻ると、 fd に関連しているすべての knotes は、もはやありません。削除された knotes は、 kevent(2) 呼び出しから決して返されないので、ユーザランドで、リソースを追跡するために、 knote を使用するなら、それらはリーク (leak) されます。ファイル記述子を追加するか、削除することができないように、 knote_fdclose() の呼び出し以降も FILEDESC_LOCK() ロックを保持しなければなりません。
knlist_*() 関数ファミリは、オブジェクトに関連している knotes を管理します。 knlist は、必要ではありませんが、共通に使用されます。使用されるなら、 knlist は、 knlist_init(), knlist_init_mtx() または knlist_init_rw_reader() のいずれかで初期化されなければなりません。 knlist 構造体は、オブジェクトの構造体に埋め込まれます。 lock は、 f_event 呼び出し以降も保持されます。
knlist_init() 関数に関して、 lock が NULL であるなら、共有されるグローバルなロックが使用され、残りの引数は、 NULL でなければなりません。関数ポインタ kl_lock, kl_unlock と kl_locked は、引数 lock を操作するために使用されます。関数ポインタのいずれかが NULL であるなら、 MTX_DEF スタイルの mutex(9) ロックで操作されるる関数が、代わりに使用されます。
関数 knlist_init_mtx() は、 lock が MTX_DEF スタイルの mutex(9) ロックであるときに、 knlist を初期化するために使用されます。
関数 knlist_init_rw_reader() は、 lock が rwlock(9) 読み込みロックであるとき、 knlist を初期化するために使用されます。ロックは、 rw_rlock() 関数によって獲得されます。
関数 knlist_empty() は、リストに knotes がないとき、真を返します。関数は、呼び出されるとき、 lock が保持されていることを必要とします。
関数 knlist_clear() は、リストからすべての knotes を削除します。 islocked 引数は、 lock が獲得されているなら、宣言します。すべての knotes には、 knote が返され、次のスキャンの間に削除されるように、 EV_ONESHOT 設定があります。 f_detach 関数は、 knote が次のスキャンの間に削除されるとき、呼び出されます。この関数は、 fdrop() の td 引数が NULL となるように、 f_isfd が struct filterops に設定されるとき、使用されてはいけません。
関数 knlist_delete() は、リストのすべての knotes を取り除き削除します。関数 f_detach は、呼び出されなくて、 knote は、次のスキャンで返されません。この関数の使用は、プロセスがリソースを追跡するために knote を使用するなら、ユーザランドのリソースを漏らすかもしれません。
knlist_clear() と knlist_delete() 関数の両方は、スリープするかもしれません。また、それらは、使い果たす他の knotes をウェートするために lock を解放します。
knlist_destroy() 関数は、 knlist を破壊するために使用されます。 knlist ( knlist_empty() は、真を返す) に関連している knotes があるはずがありません、それ以上の knotes は、オブジェクトにアタッチされません。 knlist は、 knlist_clear() または knlist_delete() を呼び出すことによって、空にされます。
マクロ KNOTE_LOCKED() と KNOTE_UNLOCKED() は、オブジェクトに関連しているイベントに関して knotes に通知するために使用されます。 knote に関連している f_event 関数の呼び出しリストで、すべての knotes を繰り返します。 knl に関連しているロックが保持されているなら、マクロ KNOTE_LOCKED() が使用されなければなりません。関数 KNOTE_UNLOCKED() は、 knotes のリストで繰り返す前にロックを獲得します。
戻り値
関数 kqueue_add_filteropts() は、成功すれば、0 を返し、無効の filt の場合は、 EINVAL を返し、フィルタが既にインストールされているなら、 EEXIST を返します。関数 kqueue_del_filteropts() は、成功すれば、0 を返し、無効の filt の場合は、 EINVAL を返し、フィルタがまだ使用中であるなら、 EBUSY を返します。
関数 kqfd_register() は、成功すれば、0 を返し、ファイル記述子が kqueue でないか、または kevent(2) によって返された任意の指定可能な値でないなら、 EBADF を返します。
作者
このマニュアルページは、 <jmg@FreeBSD.org>によって書かれました。March 26, 2012 | FreeBSD |