EN JA
KQUEUE(9)
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 keventident は、ファイル記述子を取ります。この場合、 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 は、 knotekn_statusKN_DETACHED ビットをクリアしなければなりません。関数は、成功すれば、0 を返し、オブジェクトが破壊されているか、または存在しないときのように、失敗すれば、適切なエラーを返します。 f_attach の間に、 kn_fops ポインタを異なったポインタに変更することは有効です。これは、 knote を処理するとき呼び出される f_eventf_detach 関数を変更します。
f_detach
f_detach 関数は、 knoteknlist_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 が追加された knlistkl_lock 関数で獲得しなければなりません。

関数 kqfd_register() は、kqueue ファイル記述子 fdkevent を登録します。スリープが安全であるなら、 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() 関数に関して、 lockNULL であるなら、共有されるグローバルなロックが使用され、残りの引数は、 NULL でなければなりません。関数ポインタ kl_lock, kl_unlockkl_locked は、引数 lock を操作するために使用されます。関数ポインタのいずれかが NULL であるなら、 MTX_DEF スタイルの mutex(9) ロックで操作されるる関数が、代わりに使用されます。

関数 knlist_init_mtx() は、 lockMTX_DEF スタイルの mutex(9) ロックであるときに、 knlist を初期化するために使用されます。

関数 knlist_init_rw_reader() は、 lockrwlock(9) 読み込みロックであるとき、 knlist を初期化するために使用されます。ロックは、 rw_rlock() 関数によって獲得されます。

関数 knlist_empty() は、リストに knotes がないとき、真を返します。関数は、呼び出されるとき、 lock が保持されていることを必要とします。

関数 knlist_clear() は、リストからすべての knotes を削除します。 islocked 引数は、 lock が獲得されているなら、宣言します。すべての knotes には、 knote が返され、次のスキャンの間に削除されるように、 EV_ONESHOT 設定があります。 f_detach 関数は、 knote が次のスキャンの間に削除されるとき、呼び出されます。この関数は、 fdrop() の td 引数が NULL となるように、 f_isfdstruct 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 を返します。

関連項目

kevent(2), kqueue(2)

作者

このマニュアルページは、 John-Mark Gurney <jmg@FreeBSD.org>によって書かれました。
March 26, 2012 FreeBSD