## Tcl9.0.3/Tk9.0.3 Documentation > Tcl C API > Notifier

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier — 行事待ち行列と通知譜対話機能　the event queue and notifier interfaces
  SYNOPSIS
    #include <tcl.h>
    Tcl_CreateEventSource(setupProc, checkProc, clientData)
    Tcl_DeleteEventSource(setupProc, checkProc, clientData)
    Tcl_SetMaxBlockTime(timePtr)
    Tcl_QueueEvent(evPtr, position)
    Tcl_ThreadQueueEvent(threadId, evPtr, position)
    Tcl_ThreadAlert(threadId)
    Tcl_ThreadId
    Tcl_GetCurrentThread()
    Tcl_DeleteEvents(deleteProc, clientData)
    void *
    Tcl_InitNotifier()
    Tcl_FinalizeNotifier(clientData)
    int
    Tcl_WaitForEvent(timePtr)
    Tcl_AlertNotifier(clientData)
    Tcl_SetTimer(timePtr)
    int
    Tcl_ServiceAll()
    int
    Tcl_ServiceEvent(flags)
    int
    Tcl_GetServiceMode()
    int
    Tcl_SetServiceMode(mode)
    Tcl_ServiceModeHook(mode)
    Tcl_SetNotifier(notifierProcPtr)
  引数 ARGUMENTS
    Tcl_EventSetupProc *setupProc (入力in)
    Tcl_EventCheckProc *checkProc (入力in)
    void *clientData (入力in)
    const Tcl_Time *timePtr (入力in)
    Tcl_Event *evPtr (入力in)
    int position (入力in)
    Tcl_ThreadId threadId (入力in)
    Tcl_EventDeleteProc *deleteProc (入力in)
    int flags (入力in)
    int mode (入力in)
    const Tcl_NotifierProcs* (notifierProcPtr)
  緒論 INTRODUCTION
  告知の基本 NOTIFIER BASICS
  CREATING A NEW EVENT SOURCE
    TCL_QUEUE_TAIL
    TCL_QUEUE_HEAD
    TCL_QUEUE_MARK
    TCL_QUEUE_ALERT_IF_EMPTY
  CREATING A NEW NOTIFIER
  告知譜の置換え REPLACING THE NOTIFIER
  EXTERNAL EVENT LOOPS
  SEE ALSO
  KEYWORDS

### NAME

Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_ThreadQueueEvent, Tcl_ThreadAlert, Tcl_GetCurrentThread, Tcl_DeleteEvents, Tcl_InitNotifier, Tcl_FinalizeNotifier, Tcl_WaitForEvent, Tcl_AlertNotifier, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode, Tcl_ServiceModeHook, Tcl_SetNotifier — 行事待ち行列と通知譜対話機能　the event queue and notifier interfaces

### SYNOPSIS

#include <tcl.h>
Tcl_CreateEventSource(setupProc, checkProc, clientData)
Tcl_DeleteEventSource(setupProc, checkProc, clientData)
Tcl_SetMaxBlockTime(timePtr)
Tcl_QueueEvent(evPtr, position)
Tcl_ThreadQueueEvent(threadId, evPtr, position)
Tcl_ThreadAlert(threadId)
Tcl_ThreadId
Tcl_GetCurrentThread()
Tcl_DeleteEvents(deleteProc, clientData)
void *
Tcl_InitNotifier()
Tcl_FinalizeNotifier(clientData)
int
Tcl_WaitForEvent(timePtr)
Tcl_AlertNotifier(clientData)
Tcl_SetTimer(timePtr)
int
Tcl_ServiceAll()
int
Tcl_ServiceEvent(flags)
int
Tcl_GetServiceMode()
int
Tcl_SetServiceMode(mode)
Tcl_ServiceModeHook(mode)
Tcl_SetNotifier(notifierProcPtr)

### 引数 ARGUMENTS

Tcl_EventSetupProc *setupProc (入力in)
  Tcl_DoOneEvent 内で行事待ちの為の用意を起動する手続函数｡ Procedure to invoke to prepare for event wait in Tcl_DoOneEvent.

Tcl_EventCheckProc *checkProc (入力in)
  行事を待った後に起動する為の Tcl_DoOneEvent の為の手続函数｡何かの行事が起ったかを監視し､起ればそれを待ち行列にする｡ Procedure for Tcl_DoOneEvent to invoke after waiting for events. Checks to see if any events have occurred and, if so, queues them.

void *clientData (入力in)
  setupProc か checkProc か deleteProc に渡す任意の一語｡ Arbitrary one-word value to pass to setupProc, checkProc, or deleteProc.

const Tcl_Time *timePtr (入力in)
  行事の為に待つ時間の最大量を指し示す｡これは期間(如何に長くまつか)､として指示し､絶対時刻(何時覚醒するか)ではない｡もし Tcl_WaitForEvent に渡される指示子が NULLなら､それは待ち時間の最大値は無いことを意味する: 必要なら永遠に待つ｡ Indicates the maximum amount of time to wait for an event. This is specified as an interval (how long to wait), not an absolute time (when to wakeup). If the pointer passed to Tcl_WaitForEvent is NULL, it means there is no maximum wait time: wait forever if necessary.

Tcl_Event *evPtr (入力in)
  行事待ち行列に加える行事｡行事の貯蔵域は呼出し元により Tcl_Alloc を使って割当てられている｡ An event to add to the event queue. The storage for the event must have been allocated by the caller using Tcl_Alloc.

int position (入力in)
  待ち行列内に新しい行事を追加する場所: TCL_QUEUE_TAILとTCL_QUEUE_HEADとTCL_QUEUE_MARKと､ 待ち行列が空の場合､警告すべきか: TCL_QUEUE_ALERT_IF_EMPTY｡　　　　　　　 Where to add the new event in the queue: TCL_QUEUE_TAIL, TCL_QUEUE_HEAD, TCL_QUEUE_MARK, and whether to do an alert if the queue is empty: TCL_QUEUE_ALERT_IF_EMPTY.

Tcl_ThreadId threadId (入力in)
  多重時分割片の為の唯一の識別子｡ A unique identifier for a thread.

Tcl_EventDeleteProc *deleteProc (入力in)
  Tcl_DeleteEvents 内の夫々の待ち行列行事の為に起動する手続函数｡ Procedure to invoke for each queued event in Tcl_DeleteEvents.

int flags (入力in)
  役務処理する為の行事の型｡これら旗印は Tcl_DoOneEvent に渡されたものと同一である｡ What types of events to service. These flags are the same as those passed to Tcl_DoOneEvent.

int mode (入力in)
  Tcl_ServiceAll により行事が処理されるべきかを指示する｡TCL_SERVICE_NONE か TCL_SERVICE_ALL のどれか一つでなければならない｡ Indicates whether events should be serviced by Tcl_ServiceAll. Must be one of TCL_SERVICE_NONE or TCL_SERVICE_ALL.

const Tcl_NotifierProcs* (notifierProcPtr)
  告知譜手続函数を記述している機能指示子の構造であり､実行可能譜内に実装されたものと置換えられる為のものである｡詳細は REPLACING THE NOTIFIER を参照されたい｡ Structure of function pointers describing notifier procedures that are to replace the ones installed in the executable. See REPLACING THE NOTIFIER for details.

### 緒論 INTRODUCTION

ここで記述されている対話機能は Tcl 行事巡回の誂えに使用される｡ 二つの大部分の普通の誂えは､その中に Tcl が埋込まれた応用譜によって提供されるものの様に､新しい行事源資に加え､他の行事巡回と一緒にTcl の行事巡回に併合する為のものである｡ これらのそれぞれの業務は別に下の節で記述される｡ The interfaces described here are used to customize the Tcl event loop. The two most common customizations are to add new sources of events and to merge Tcl's event loop with some other event loop, such as one provided by an application in which Tcl is embedded. Each of these tasks is described in a separate section below.

この取扱説明書見出しの手続函数は Tcl 行事告知子が造られる基盤である｡ Tcl 行事告知子は Tcl 行事仕組み内の最も基礎の層である: The procedures in this manual entry are the building blocks out of which the Tcl event notifier is constructed. The event notifier is the lowest layer in the Tcl event mechanism. It consists of three things:

1. 行事源資: これらは､行事が生成され得る方法を表す｡譬えば､ Tcl_CreateTimerHandler 手続函数と after を実装する時間行事原資がある､又､ Unix 系の上では Tcl_CreateFileHandler を実装するファイル行事がある｡行事源資は､適正な時に行事を検出する為に告知資と一緒に働き､行事待ち行連にそれを記録し､最終的に高級ソフトに行事が生じたことを告知しなければならない｡手続函数 Tcl_CreateEventSource, Tcl_DeleteEventSource, and Tcl_SetMaxBlockTime, Tcl_QueueEvent, and Tcl_DeleteEvents は主として行事原資によって使用される｡ Event sources: these represent the ways in which events can be generated. For example, there is a timer event source that implements the Tcl_CreateTimerHandler procedure and the after command, and there is a file event source that implements the Tcl_CreateFileHandler procedure on Unix systems. An event source must work with the notifier to detect events at the right times, record them on the event queue, and eventually notify higher-level software that they have occurred. The procedures Tcl_CreateEventSource, Tcl_DeleteEventSource, and Tcl_SetMaxBlockTime, Tcl_QueueEvent, and Tcl_DeleteEvents are used primarily by event sources.

2. 行事待ち行列: 検出されたが､役務が果されていない行事を含んでいる､ Tcl 解釈実行機能を含んでいるそれぞれの時分割片の為の一つの待ち行列がある｡行事源資は､行事巡回の間の適正な時間に処理される為に､待ち行列に行事を置く｡その行事待ち行列は､どの行事源資も他のものを立ち枯れさせない様､行事処理の公正な規律を保障する｡又将来の時刻に役務をさせる為に行事を貯めることを許容する｡Tcl_QueueEvent は(主として行事源資により)､行事を現在の時分割片の待ち行列に加える為に使われ､Tcl_DeleteEvents は行事を処理することなく待ち行列から行事を取去ることに使用される｡ The event queue: there is a single queue for each thread containing a Tcl interpreter, containing events that have been detected but not yet serviced. Event sources place events onto the queue so that they may be processed in order at appropriate times during the event loop. The event queue guarantees a fair discipline of event handling, so that no event source can starve the others. It also allows events to be saved for servicing at a future time. Tcl_QueueEvent is used (primarily by event sources) to add events to the current thread's event queue and Tcl_DeleteEvents is used to remove events from the queue without processing them.

3. 行事巡回: 行事を検出し処理する為に､応用譜は行事が生じることを待つ巡回に入り､行事待ち行列に置き､そして処理する｡大多数の応用譜は手続函数 Tcl_DoOneEvent を呼ぶ事によりこれを行う､それは取扱説明書の別の見出し内で記述される｡ The event loop: in order to detect and process events, the application enters a loop that waits for events to occur, places them on the event queue, and then processes them. Most applications will do this by calling the procedure Tcl_DoOneEvent, which is described in a separate manual entry.

大多数の Tcl 往々譜は Tcl 告知譜のどのような内容も考慮する必要はない｡但し､告知譜は新しいOSの為､或は外部行事巡回を使用する(Tcl がMotif 応用譜に埋め込まれた時には､恰も Motif 行事巡回の如く)為の双方を再目的として充分な柔軟性を有する｡手続函数 Tcl_WaitForEvent と Tcl_SetTimer は通常 Tcl により実装されるが､告知譜を再目的化する為に新しい版に置き換えられるかもしれない( Tcl_InitNotifier, Tcl_AlertNotifier, Tcl_FinalizeNotifier, Tcl_Sleep, Tcl_CreateFileHandler と Tcl_DeleteFileHandler も置き換えられなければならない; 詳細は下の CREATING A NEW NOTIFIER を参照されたい)｡手続函数 Tcl_ServiceAll と Tcl_ServiceEvent と Tcl_GetServiceMode と Tcl_SetServiceMode は､ MotifのもののようにTcl の行事巡回を外部行事巡回に結合する手助けを提供する｡ Most Tcl applications need not worry about any of the internals of the Tcl notifier. However, the notifier now has enough flexibility to be retargeted either for a new platform or to use an external event loop (such as the Motif event loop, when Tcl is embedded in a Motif application). The procedures Tcl_WaitForEvent and Tcl_SetTimer are normally implemented by Tcl, but may be replaced with new versions to retarget the notifier (the Tcl_InitNotifier, Tcl_AlertNotifier, Tcl_FinalizeNotifier, Tcl_Sleep, Tcl_CreateFileHandler, and Tcl_DeleteFileHandler must also be replaced; see CREATING A NEW NOTIFIER below for details). The procedures Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, and Tcl_SetServiceMode are provided to help connect Tcl's event loop to an external event loop such as Motif's.

### 告知の基本 NOTIFIER BASICS

告知譜が如何に働くかを理解する最も容易な方法は Tcl_DoOneEvent が呼ばれた時に何が起るかを考慮することである｡どのような種類の行事が処理に適しているか､又更にどの行事も用意できないない時に抑制するか否かを指し示す旗印引数 flags が Tcl_DoOneEvent に渡される｡Tcl_DoOneEvent は次のことに従う: 　　　　 The easiest way to understand how the notifier works is to consider what happens when Tcl_DoOneEvent is called. Tcl_DoOneEvent is passed a flags argument that indicates what sort of events it is OK to process and also whether or not to block if no events are ready. Tcl_DoOneEvent does the following things:

1. 役務処理され得る何かの行事が含まれているか否かを見る為に行事待ち行列を確認する｡もしあれば､最初のありうる行事を役務処理し､待ち行列から除去して帰る｡それをTcl_ServiceEvent を呼出しその旗印引数に渡して行う｡ Check the event queue to see if it contains any events that can be serviced. If so, service the first possible event, remove it from the queue, and return. It does this by calling Tcl_ServiceEvent and passing in the flags argument.

2. 行事の為の抑制を準備する｡これを行う為に､ Tcl_DoOneEvent はそれぞれの行事源資内の設定用手続函数を起動する｡行事源資は行事源資固有の初期設定を遂行し､新しい行事が起らない場合 Tcl_WaitForEvent はどれだけ長く抑制するかを限定する為に Tcl_SetMaxBlockTime を呼ぶかもしれない｡ Prepare to block for an event. To do this, Tcl_DoOneEvent invokes a setup procedure in each event source. The event source will perform event-source specific initialization and possibly call Tcl_SetMaxBlockTime to limit how long Tcl_WaitForEvent will block if no new events occur.

3. Tcl_WaitForEvent を呼出す｡この手続函数は異なるOS上で別に実装される; それは､行事源資によって提供された情報を基に､行事の発生を待つ､それは､ timePtr が期間を 0 以外に指定した場合は応用譜を抑制することを惹き起こすかもしれない｡Tcl_WaitForEvent は､ファイルが可読になったり､ timePtr で与えた期間が満了したりの様な何かが生じた時には､Tcl_WaitForEvent は帰る｡ Tcl_WaitForEvent の為にもし待つべき行事がなく､抑制が永続する場合､それはすぐさま帰り､ Tcl_DoOneEvent は0を返す｡ Call Tcl_WaitForEvent. This procedure is implemented differently on different platforms; it waits for an event to occur, based on the information provided by the event sources. It may cause the application to block if timePtr specifies an interval other than 0. Tcl_WaitForEvent returns when something has happened, such as a file becoming readable or the interval given by timePtr expiring. If there are no events for Tcl_WaitForEvent to wait for, so that it would block forever, then it returns immediately and Tcl_DoOneEvent returns 0.

4. それぞれの行事源資の中で確認手続函数 check procedure を呼出す｡その確認手続函数は､この原資に対してどれかの関連する行事が起ったかを定める｡もしそうなら､行事は行事待ち行列に加えられる｡ Call a check procedure in each event source. The check procedure determines whether any events of interest to this source occurred. If so, the events are added to the event queue.

5. どれかが役務処理され得る行事が含まれているか､行事待ち行列を確認する｡そうであれば､最初の可能な行事を処理し､待ち行列から取除き､そして戻る｡ Check the event queue to see if it contains any events that can be serviced. If so, service the first possible event, remove it from the queue, and return.

6. 空回りの仕掛り呼戻しがないか見る｡そうであれば､それら全てを起動し､帰る｡ See if there are idle callbacks pending. If so, invoke all of them and return.

7. どの行事も準備できていない事を指し示す 0 を返すか､呼出し元に抑制が要求されていれば [2] の段階に戻る｡ Either return 0 to indicate that no events were ready, or go back to step [2] if blocking was requested by the caller.

### CREATING A NEW EVENT SOURCE

行事源資は､告知譜に起動された三つの手続函数､及び､行事駆動呼戻しを編成する為に高級水準符号により起動された追加的Ｃ言語手続函数とで構成される｡その三つの手続函数は､上記で記述された設定と確認の手続函数､及び､役務処理のための行事待ち行列から行事が除去された時に起動される追加的手続函数とから構成される｡ An event source consists of three procedures invoked by the notifier, plus additional C procedures that are invoked by higher-level code to arrange for event-driven callbacks. The three procedures called by the notifier consist of the setup and check procedures described above, plus an additional procedure that is invoked when an event is removed from the event queue for servicing.

手続函数 Tcl_CreateEventSource は新しい行事源資を生成する｡その引数は行事源資のための､設定用手続函数と確認用手続函数を指定する｡設定用手続函数 SetupProc は次の規範的原型に合致すべきであろう: The procedure Tcl_CreateEventSource creates a new event source. Its arguments specify the setup procedure and check procedure for the event source. SetupProc should match the following prototype:

    typedef void Tcl_EventSetupProc(
            void *clientData,
            int flags);

この clientData 引数はTcl_CreateEventSource への clientData 引数と同一になる; それは典型的には行事源資によって管理される私的情報を指す事に使用される｡この旗印引数は､Tcl_DoOneEvent に渡された旗印と同一になる､但し違いとして､ 0 になる事はない(Tcl_DoOneEvent は 0 を TCL_ALL_EVENTS に置換える)｡旗印はどの種類の行事が考慮されるかをさし示す; もしこの行事源資に相当するビットが設定されない場合､この行事源資は何もすることなくすぐさま帰る｡譬えば､ファイル行事源資は TCL_FILE_EVENTS ビットを確認する｡ The clientData argument will be the same as the clientData argument to Tcl_CreateEventSource; it is typically used to point to private information managed by the event source. The flags argument will be the same as the flags argument passed to Tcl_DoOneEvent except that it will never be 0 (Tcl_DoOneEvent replaces 0 with TCL_ALL_EVENTS). Flags indicates what kinds of events should be considered; if the bit corresponding to this event source is not set, the event source should return immediately without doing anything. For example, the file event source checks for the TCL_FILE_EVENTS bit.

設定用手続函数 SetupProc の担当責務は､望ましい型の行事が生じた時､応用譜を覚醒することを確かにすることである｡これは典型的にはOS依存の様式で遂行される｡譬えば､ Unix の元では行事源資は Tcl_CreateFileHandler を呼出すであろう; Windows では Windowsの行事によって告知が要求されるであろう｡時刻行事や､又は何かの定期巡回行事の様な､時刻駆動の為に､行事源資は､縦え行事が起きなくとも､指定された時刻の後に覚醒する為の応用譜を強制する為に､ Tcl_SetMaxBlockTime を呼出すことが可能である｡もし､どの行事源資も Tcl_SetMaxBlockTime を呼ばない場合､Tcl_WaitForEvent は行事が生じる為に必要な長さだけ待つ; 呼ばれた場合､行事源資の中の一つにより Tcl_SetMaxBlockTime に渡される最短の期間だけ待つ｡もし､行事源資が既に報告する為に行事を用意させることが判っている場合､それは抑制時間最大零を要求する事ができる｡譬えば､ X 行事源資のための設定用手続函数は､既に行列になった行事があるかを観察しているかのように見える｡もし､あれば､それは0抑制時間を伴って Tcl_SetMaxBlockTime を呼ぶ､そこで､もし X 接続上の新しいデータが無ければ､Tcl_WaitForEvent は抑制はしない｡ Tcl_WaitForEvent への timePtr 引数は､時間期間を秒又は､厘秒で記述している構造を指している｡ SetupProc's job is to make sure that the application wakes up when events of the desired type occur. This is typically done in a platform-dependent fashion. For example, under Unix an event source might call Tcl_CreateFileHandler; under Windows it might request notification with a Windows event. For timer-driven event sources such as timer events or any polled event, the event source can call Tcl_SetMaxBlockTime to force the application to wake up after a specified time even if no events have occurred. If no event source calls Tcl_SetMaxBlockTime then Tcl_WaitForEvent will wait as long as necessary for an event to occur; otherwise, it will only wait as long as the shortest interval passed to Tcl_SetMaxBlockTime by one of the event sources. If an event source knows that it already has events ready to report, it can request a zero maximum block time. For example, the setup procedure for the X event source looks to see if there are events already queued. If there are, it calls Tcl_SetMaxBlockTime with a 0 block time so that Tcl_WaitForEvent does not block if there is no new data on the X connection. The timePtr argument to Tcl_WaitForEvent points to a structure that describes a time interval in seconds and microseconds:

    typedef struct {
        long long sec;
        long usec;
    } Tcl_Time;

この usec 欄は 1000000 より少なくすべきである｡ The usec field should be less than 1000000.

Tcl_SetMaxBlockTime に提供される情報は Tcl_WaitForEvent への次の呼出しの為にのみ使用される; それは､Tcl_WaitForEvent が帰った後､棄捨される｡次回行事待ちはそれぞれの行事源資の設定用手続函数が再び呼ばれて実施される､又､それは､その行事を待つ為の新しい情報を指定できる｡ Information provided to Tcl_SetMaxBlockTime is only used for the next call to Tcl_WaitForEvent; it is discarded after Tcl_WaitForEvent returns. The next time an event wait is done each of the event sources' setup procedures will be called again, and they can specify new information for that event wait.

もし応用譜が Tcl_DoOneEvent よりも外部行事巡回を使用する場合､行事源資は､その他の時刻に､ Tcl_SetMaxBlockTime を呼出す必要があるかもしれない｡譬えば､もし､行事の為に巡回の必要性がある新しい行事処理子が登録された場合､行事源資は､Tcl を呼出す為の外部行事巡回を強制する為に抑制時間を零にする為に Tcl_SetMaxBlockTime を呼ぶかも知れない｡ Tcl_DoOneEvent か Tcl_ServiceAll への最後の呼出し以降に見られた最短の期間で Tcl_SetMaxBlockTime は Tcl_SetTimer を起動する｡ If the application uses an external event loop rather than Tcl_DoOneEvent, the event sources may need to call Tcl_SetMaxBlockTime at other times. For example, if a new event handler is registered that needs to poll for events, the event source may call Tcl_SetMaxBlockTime to set the block time to zero to force the external event loop to call Tcl. In this case, Tcl_SetMaxBlockTime invokes Tcl_SetTimer with the shortest interval seen since the last call to Tcl_DoOneEvent or Tcl_ServiceAll.

そのOS上で Tcl_WaitForEvent によって追加の情報が必要とされた場合は､共通の手続函数 Tcl_SetMaxBlockTime に加えて､他のOS固有の手続函数が設定用手続函数 setupProc の為に利用できるかもしれない｡譬えば､ Unix 系上では､Tcl_CreateFileHandler 対話譜がファイル行事を待つために使用可能である｡ 　　　　　 In addition to the generic procedure Tcl_SetMaxBlockTime, other platform-specific procedures may also be available for setupProc, if there is additional information needed by Tcl_WaitForEvent on that platform. For example, on Unix systems the Tcl_CreateFileHandler interface can be used to wait for file events.

それぞれの行事源資によりもたらされた第二の手続函数は､その確認手続函数であり､ Tcl_CreateEventSource への checkProc 引数により指定される｡ checkProc は次の規範的原型に合致しなければならない｡ The second procedure provided by each event source is its check procedure, indicated by the checkProc argument to Tcl_CreateEventSource. CheckProc must match the following prototype:

    typedef void Tcl_EventCheckProc(
            void *clientData,
            int flags);

この手続函数への引数は､ setupProc の為のものと同一である｡checkProc は､行事を待った後に Tcl_DoOneEvent によって起動される｡多分､少なくとも一つの行事源資は､行事を待つ為に､今､用意されている｡Tcl_DoOneEvent はそれぞれの行事を交替に呼出すので､それら全ては､用意された何かの行事の列を作る可能性を有する｡確認用手続函数は､二つのことを行う｡第１は､何かの行事が起動されたかを見なければならない｡異なる行事源資は異なる方法でこれを行う｡ The arguments to this procedure are the same as those for setupProc. CheckProc is invoked by Tcl_DoOneEvent after it has waited for events. Presumably at least one event source is now prepared to queue an event. Tcl_DoOneEvent calls each of the event sources in turn, so they all have a chance to queue any events that are ready. The check procedure does two things. First, it must see if any events have triggered. Different event sources do this in different ways.

行事源資の確認手続函数は関連する行事を検出した場合､それは行事を Tcl の行事待ち行列に加えなければならない｡これを行う為に､行事源資は Tcl_QueueEvent を呼出す｡この evPtr 引数は､行事を含む動的に割当てられた構造への指示子である(記憶域管理の問題の更なる情報については下を参照されたい)｡それぞれの行事源資は､それ自身の行事構造を､如何なる情報であれあの行事源資に適正な情報と共に､定義することができる｡但し､構造の最初の要素は､ Tcl_Event 型の構造でなければならず､又､この構造の番地は行事源資と残りの告知譜との間の通信に使用される｡ Tcl_Event は次の定義を有する: If an event source's check procedure detects an interesting event, it must add the event to Tcl's event queue. To do this, the event source calls Tcl_QueueEvent. The evPtr argument is a pointer to a dynamically allocated structure containing the event (see below for more information on memory management issues). Each event source can define its own event structure with whatever information is relevant to that event source. However, the first element of the structure must be a structure of type Tcl_Event, and the address of this structure is used when communicating between the event source and the rest of the notifier. A Tcl_Event has the following definition:

    typedef struct Tcl_Event {
        Tcl_EventProc *proc;
        struct Tcl_Event *nextPtr;
    } Tcl_Event;

行事源資は Tcl_QueueEvent を呼出す前に､行事の proc 欄を埋めなくてはならない｡この nextPtr は待ち行列内の行事に連結することに使用され､又､行事源資により修正されるべきではない｡ The event source must fill in the proc field of the event before calling Tcl_QueueEvent. The nextPtr is used to link together the events in the queue and should not be modified by the event source.

行事は､Tcl_QueueEvent への引数 position の位置によって､どの三つの位置でも待ち行列に加えられても好い｡ An event may be added to the queue at any of three positions, depending on the position argument to Tcl_QueueEvent:

TCL_QUEUE_TAIL
  行事を待ち行列の後に加える､そこで全ての他の係属中の行事が先に役務処理される｡これは常に新しい行事の為の正しい位置である｡ Add the event at the back of the queue, so that all other pending events will be serviced first. This is almost always the right place for new events.

TCL_QUEUE_HEAD
  行事を待ち行列の前面に加える､そこでそれが他の行事待ち行列の前に役務処理される｡ Add the event at the front of the queue, so that it will be serviced before all other queued events.

TCL_QUEUE_MARK
  その位置が TCL_QUEUE_MARK である様な他の行事が待ち行列の前面にない限り､行事を前面に加える; もしある場合､新しい行事は他の全てのTCL_QUEUE_MARK 行事の直後に加える｡位置 position のこの値は､行列の前面に於いて､Tk 内の排他的又は､非排他的操作の間に合成された､ Enter と Leave 行事の並びの様な､整列された行事を挿入する為に使われる｡ Add the event at the front of the queue, unless there are other events at the front whose position is TCL_QUEUE_MARK; if so, add the new event just after all other TCL_QUEUE_MARK events. This value of position is used to insert an ordered sequence of events at the front of the queue, such as a series of Enter and Leave events synthesized during a grab or ungrab operation in Tk.

TCL_QUEUE_ALERT_IF_EMPTY
  Tcl_ThreadQueueEvent内で使用された時､問合せが空ならTcl_ThreadAlertの自動的呼出しに関して､整備する｡ When used in Tcl_ThreadQueueEvent arranges for an automatic call of Tcl_ThreadAlert when the queue was empty.

待ち行列から行事を扱う時刻が来ると(上述の段階１から４) Tcl_ServiceEvent は 最初に行列を待つ Tcl_Event structure 内の指定された手続函数を起動する｡手続函数は次の規範的原型に合致しなければならない: When it is time to handle an event from the queue (steps 1 and 4 above) Tcl_ServiceEvent will invoke the proc specified in the first queued Tcl_Event structure. Proc must match the following prototype:

    typedef int Tcl_EventProc(
            Tcl_Event *evPtr,
            int flags);

手続函数 proc への最初の引数は行事への指示子である､それは Tcl_QueueEvent 呼出しへの最初の引数と同一であり､待ち行列に行事を追加するものである｡手続函数 proc への第二の引数は､ Tcl_ServiceEvent への最新の呼出しの為の旗印引数 flags である; これは､行事源資により､その行事が適切でない場合にすぐさま帰る事に使われる｡ The first argument to proc is a pointer to the event, which will be the same as the first argument to the Tcl_QueueEvent call that added the event to the queue. The second argument to proc is the flags argument for the current call to Tcl_ServiceEvent; this is used by the event source to return immediately if its events are not relevant.

行事の取扱いは手続函数次第であり､典型的には一つ或はそれ以上の Tcl 命令か C言語水準の呼戻しにより起動される｡一たび行事源資が行事の取り扱いを終了すると､その行事を待ち行列から除去できることを意味する 1 を返す｡何かの理由で行事源資が､今回は行事を取扱うことができないと判断すると､行事は後に処理する為に繰り延べされるべきであることを指し示す 0 を返してもよい; この場合､ Tcl_ServiceEvent は待ち行列内の次の行事に向かい､それを役務処理しようとする｡何故､行事源資が行事を繰延べしようとするのか､幾つかの理由がある｡一つの可能性は､その行事のこの型は引数の旗印により考慮されない｡譬えば､ファイル行事源資は TCL_FILE_EVENTS ビットがその旗印の中に設定されない場合は､常に 0 を返す｡別の例では､Tk 内で､ある種の窓行事を遅延する為に Tk_RestrictEvents が起動されると､行事の遅延が生じる｡ It is up to proc to handle the event, typically by invoking one or more Tcl commands or C-level callbacks. Once the event source has finished handling the event it returns 1 to indicate that the event can be removed from the queue. If for some reason the event source decides that the event cannot be handled at this time, it may return 0 to indicate that the event should be deferred for processing later; in this case Tcl_ServiceEvent will go on to the next event in the queue and attempt to service it. There are several reasons why an event source might defer an event. One possibility is that events of this type are excluded by the flags argument. For example, the file event source will always return 0 if the TCL_FILE_EVENTS bit is not set in flags. Another example of deferring events happens in Tk if Tk_RestrictEvents has been invoked to defer certain kinds of window events.

手続函数が 1 を返す時､ Tcl_ServiceEvent は行事を行事待ち行列から取除き､その貯蔵を解き放つ｡註意すべきは､行事の為の貯蔵は Tcl_QueueEvent を呼出す前に行事源資によって割当てられなければならない( Tcl_Alloc を使用して)､しかし､それは行事源資ではなく Tcl_ServiceEvent によって解放されることになる｡ When proc returns 1, Tcl_ServiceEvent will remove the event from the event queue and free its storage. Note that the storage for an event must be allocated by the event source (using Tcl_Alloc) before calling Tcl_QueueEvent, but it will be freed by Tcl_ServiceEvent, not by the event source.

Tcl_QueueEvent 呼出しは､現在の時分割片の待ち行列に行事を加える｡他の時分割片の待ち行列に行事を加える為には､ Tcl_ThreadQueueEvent を使う｡Tcl_ThreadQueueEvent は引数として Tcl_ThreadId 引数を受取る､それは Tcl 応用譜内で重複することなく時分割片を識別する｡現在の時分割片の為の Tcl_ThreadId を得る為に､ Tcl_GetCurrentThread 手続函数を使用する｡(時分割片はこの識別子を､その待ち行列に行事を加えることができる様な他の時分割片に渡す｡)行事を他の時分割片の待ち行列に加えた後､使用者は典型的には､新しい行事に向けて警告する為の他の時分割片の告知譜を “覚醒” する為に Tcl_ThreadAlert を呼出す必要がある｡ Calling Tcl_QueueEvent adds an event to the current thread's queue. To add an event to another thread's queue, use Tcl_ThreadQueueEvent. Tcl_ThreadQueueEvent accepts as an argument a Tcl_ThreadId argument, which uniquely identifies a thread in a Tcl application. To obtain the Tcl_ThreadId for the current thread, use the Tcl_GetCurrentThread procedure. (A thread would then need to pass this identifier to other threads for those threads to be able to add events to its queue.) After adding an event to another thread's queue, you then typically need to call Tcl_ThreadAlert to “wake up” that thread's notifier to alert it to the new event.

Tcl_DeleteEvents は行事待ち行列から一つ或はそれ以上の行事を明示的に取除く為に使用する事ができる｡Tcl_DeleteEvents は待ち行列内の夫々の行事の為に手続函数を呼出し､ 1 を返す様な手続函数の為にものは削除する｡ 0 を返す様な手続函数の為の行事は待ち行列内に残される｡手続函数 Proc は次の規範的原型に合致すべきである: Tcl_DeleteEvents can be used to explicitly remove one or more events from the event queue. Tcl_DeleteEvents calls proc for each event in the queue, deleting those for with the procedure returns 1. Events for which the procedure returns 0 are left in the queue. Proc should match the following prototype:

    typedef int Tcl_EventDeleteProc(
            Tcl_Event *evPtr,
            void *clientData);

この clientData 引数は､Tcl_DeleteEvents への clientData 引数と同一になる; それは典型的には､行事源資により管理された私的情報を指すことに使用される｡この evPtr は待ち行列内の次の行事を指すことになる｡ The clientData argument will be the same as the clientData argument to Tcl_DeleteEvents; it is typically used to point to private information managed by the event source. The evPtr will point to the next event in the queue.

Tcl_DeleteEventSource は行事源資を削除する｡この setupProc と checkProc と clientData 引数は､削除される行事源資の為の Tcl_CreateEventSource に供給されたものと正確に合致しなければならない｡もしこのような源資が実在しない場合､ Tcl_DeleteEventSource は何の効果も持たない｡ Tcl_DeleteEventSource deletes an event source. The setupProc, checkProc, and clientData arguments must exactly match those provided to the Tcl_CreateEventSource for the event source to be deleted. If no such source exists, Tcl_DeleteEventSource has no effect.

### CREATING A NEW NOTIFIER

告知譜は､この取扱説明書の見出し内に記述した手続函数､及び､全てのOS上で使用可能な Tcl_DoOneEvent と Tcl_Sleep ､及び､ Unix 固有の Tcl_CreateFileHandler と Tcl_DeleteFileHandler から構成される｡大多数のこれら手続函数は共通であり､その中で､全ての告知譜は同一である｡然しながら､これら手続函数のどれもが告知譜に独立である: Tcl_InitNotifier と Tcl_AlertNotifier と Tcl_FinalizeNotifier と Tcl_SetTimer と Tcl_Sleep と Tcl_WaitForEvent と Tcl_CreateFileHandler と Tcl_DeleteFileHandler と Tcl_ServiceModeHook ｡新しいOS､又は､応用譜固有の行事巡回を伴う総合的 Tcl を運営する為､使用者はこれら手続函数の新しい版を書かなければならない｡ The notifier consists of all the procedures described in this manual entry, plus Tcl_DoOneEvent and Tcl_Sleep, which are available on all platforms, and Tcl_CreateFileHandler and Tcl_DeleteFileHandler, which are Unix-specific. Most of these procedures are generic, in that they are the same for all notifiers. However, none of the procedures are notifier-dependent: Tcl_InitNotifier, Tcl_AlertNotifier, Tcl_FinalizeNotifier, Tcl_SetTimer, Tcl_Sleep, Tcl_WaitForEvent, Tcl_CreateFileHandler, Tcl_DeleteFileHandler and Tcl_ServiceModeHook. To support a new platform or to integrate Tcl with an application-specific event loop, you must write new versions of these procedures.

Tcl_InitNotifier はこの告知譜の状態を初期化し､告知譜の状態に取扱子を返す｡Tcl はこの手続函数をTcl 解釈実行機能を初期化する時に呼出す｡Tcl_FinalizeNotifier は告知譜を閉じ､Tcl 解釈実行機能を閉じる時に Tcl_Finalize によって呼出される｡ Tcl_InitNotifier initializes the notifier state and returns a handle to the notifier state. Tcl calls this procedure when initializing a Tcl interpreter. Similarly, Tcl_FinalizeNotifier shuts down the notifier, and is called by Tcl_Finalize when shutting down a Tcl interpreter.

Tcl_WaitForEvent は､告知譜の中の最も下層の手続函数である; それは､ “関係のある” 行事が生じるか､与えられた時間が経るか､を待つことが責務である｡Tcl_WaitForEvent が起動される前に､それぞれの行事の源資の設定用の手続函数が起動されてしまう｡Tcl_WaitForEvent へのこの timePtr 引数は､設定用手続函数による Tcl_SetMaxBlockTime への呼出しと他の情報(旗印 flags 内の TCL_DONT_WAIT ビットの様な)に基き､行事の為に抑制する最大時間を与える｡ Tcl_WaitForEvent is the lowest-level procedure in the notifier; it is responsible for waiting for an “interesting” event to occur or for a given time to elapse. Before Tcl_WaitForEvent is invoked, each of the event sources' setup procedure will have been invoked. The timePtr argument to Tcl_WaitForEvent gives the maximum time to block for an event, based on calls to Tcl_SetMaxBlockTime made by setup procedures and on other information (such as the TCL_DONT_WAIT bit in flags).

理想的には､ Tcl_WaitForEvent は行事が生じることのみを待つべきである; どの様な意味でも､実際にはこうは処理されない｡ 後ほど､行事源資は生の行事を処理し､その 確認用 checkProc 手続函数の中の行事待ち行列に Tcl_Events を生成する｡しかし､(Windows の様な)ある種のOS上では､この事は可能ではない; 待ち行列を含む Tcl_Events やその他を含み､行事は Tcl_WaitForEvent 内で処理され得る(譬えば､固有の部品の為の呼戻しが起動され得る)｡ Tcl_WaitForEvent からの帰り値は 0 か 1 か -1 の内のどれかでなければならない｡ Windows の様なOS上では､行事は Tcl_WaitForEvent 内で処理させる､帰り値の 1 は猶も処理されずに仕掛かりの行事があることを意味する｡ これは､もし全ての仕掛かり行事が処理されることを望む場合､ Tcl_WaitForEvent を再度呼出さねばならないとの､呼出し元への信号である｡帰り値が 0 の意味は､再度の Tcl_WaitForEvent 呼出しは何の効果もないことである: これは､ Tcl_WaitForEvent のみがどの行事処理もすることなく待つ様なOSである場合も､ Tcl_WaitForEvent が､処理すべき追加的行事が存在しないことを確信している(譬えば､時間が経過した理由で帰った)場合も､成立する｡最後に､帰り値が -1 の意味は､行事巡回は最早や､使用可能ではなく､応用譜は恐らく解除され終了する｡Windowsの元では､これは WM_QUIT 伝言文を受取った時に生じる;Unix では､活動中の行事源資が無く､且つ､期限切れは無限大の為に Tcl_WaitForEvent が永遠に待たされるときに生じる｡ 　　　　　　　　 Ideally, Tcl_WaitForEvent should only wait for an event to occur; it should not actually process the event in any way. Later on, the event sources will process the raw events and create Tcl_Events on the event queue in their checkProc procedures. However, on some platforms (such as Windows) this is not possible; events may be processed in Tcl_WaitForEvent, including queuing Tcl_Events and more (for example, callbacks for native widgets may be invoked). The return value from Tcl_WaitForEvent must be either 0, 1, or -1. On platforms such as Windows where events get processed in Tcl_WaitForEvent, a return value of 1 means that there may be more events still pending that have not been processed. This is a sign to the caller that it must call Tcl_WaitForEvent again if it wants all pending events to be processed. A 0 return value means that calling Tcl_WaitForEvent again will not have any effect: either this is a platform where Tcl_WaitForEvent only waits without doing any event processing, or Tcl_WaitForEvent knows for sure that there are no additional events to process (e.g. it returned because the time elapsed). Finally, a return value of -1 means that the event loop is no longer operational and the application should probably unwind and terminate. Under Windows this happens when a WM_QUIT message is received; under Unix it happens when Tcl_WaitForEvent would have waited forever because there were no active event sources and the timeout was infinite.

Tcl_AlertNotifier はどの多重分割片にも､その待ち行列上の新しい行事へ警告する為に､告知譜を “覚醒させる” ことを許容するために使用される｡Tcl_AlertNotifier は引数として､ Tcl_InitNotifier によって返された告知譜処理子を要求する｡ Tcl_AlertNotifier is used to allow any thread to “wake up” the notifier to alert it to new events on its queue. Tcl_AlertNotifier requires as an argument the notifier handle returned by Tcl_InitNotifier.

もし警告譜が外部行事巡回と共に使用される場合､それは Tcl_SetTimer 対話機能を運営しなければならない｡Tcl_SetTimer は､何時であれ最大抑制時間が減じる時は､ Tcl_SetMaxBlockTime によって起動される｡Tcl_SetTimer は外部行事巡回に関して､縦えもし何も行事が起らなくても､指定された期間の後に Tcl_ServiceAll を起動する様に手配すべきである｡この対話処理機能は 外部行事巡回がある時に､Tcl_WaitForEvent が起動されないので必要である｡もし告知譜が Tcl_DoOneEvent からのみ使用される場合､Tcl_SetTimer は何もする必要がない｡ If the notifier will be used with an external event loop, then it must also support the Tcl_SetTimer interface. Tcl_SetTimer is invoked by Tcl_SetMaxBlockTime whenever the maximum blocking time has been reduced. Tcl_SetTimer should arrange for the external event loop to invoke Tcl_ServiceAll after the specified interval even if no events have occurred. This interface is needed because Tcl_WaitForEvent is not invoked when there is an external event loop. If the notifier will only be used from Tcl_DoOneEvent, then Tcl_SetTimer need not do anything.

Tcl_ServiceModeHook は､依頼譜に Tcl_SetServiceMode を呼出させる時は､告知譜のOSに独立の部分から呼出される｡この鈎爪は､応用譜が排他的巡回に入った時に特別の行事取扱を要求する､OSを運営する為に提供される(Windowsの告知譜は､譬えば､この鈎爪を通信窓を生成する為に使用する)｡ Tcl_ServiceModeHook is called by the platform-independent portion of the notifier when client code makes a call to Tcl_SetServiceMode. This hook is provided to support operating systems that require special event handling when the application is in a modal loop (the Windows notifier, for instance, uses this hook to create a communication window).

Unix 系では､ファイル行事源資は又､告知譜からの要求を運営している｡ファイル行事源資は Tcl_CreateFileHandler と Tcl_DeleteFileHandler 手続函数から構成され､それは､取扱説明書の Tcl_CreateFileHandler 内に記述されている｡ On Unix systems, the file event source also needs support from the notifier. The file event source consists of the Tcl_CreateFileHandler and Tcl_DeleteFileHandler procedures, which are described in the Tcl_CreateFileHandler manual page.

Tcl_Sleep と Tcl_DoOneEvent 対話機能は関連する取扱説明書の頁に記載されている｡ The Tcl_Sleep and Tcl_DoOneEvent interfaces are described in their respective manual pages.

新しい告知譜を作成する最も容易な方法は､ Tcl 源資配布元内の unix/tclUnixNotfy.c や win/tclWinNotify.c のファイルの様な､既存の告知譜の符号命令を見ることである｡ The easiest way to create a new notifier is to look at the code for an existing notifier, such as the files unix/tclUnixNotfy.c or win/tclWinNotify.c in the Tcl source distribution.

### 告知譜の置換え REPLACING THE NOTIFIER

上記の慣習に従って書かれた告知譜は標準告知譜の位置の実行時処理内に実装することができる｡この仕組みが､使用されるので､一つの実行可能譜が､電網閲覧機能部品譜の様に､(標準告知譜と共に)標準-独立算譜として使用することができ､又､(積込み可能な拡張内に告知譜の置換により)他の算譜への拡張譜として再使用される｡ A notifier that has been written according to the conventions above can also be installed in a running process in place of the standard notifier. This mechanism is used so that a single executable can be used (with the standard notifier) as a stand-alone program and reused (with a replacement notifier in a loadable extension) as an extension to another program, such as a Web browser plugin.

これを行う為に､この拡張は Tcl_NotifierProcs データ構造への指示子を渡して Tcl_SetNotifier への呼出しをさせる｡この構造は次の配置を有する: 　　　　　 To do this, the extension makes a call to Tcl_SetNotifier passing a pointer to a Tcl_NotifierProcs data structure. The structure has the following layout:

    typedef struct {
        Tcl_SetTimerProc *setTimerProc;
        Tcl_WaitForEventProc *waitForEventProc;
        Tcl_CreateFileHandlerProc *createFileHandlerProc;
        Tcl_DeleteFileHandlerProc *deleteFileHandlerProc;
        Tcl_InitNotifierProc *initNotifierProc;
        Tcl_FinalizeNotifierProc *finalizeNotifierProc;
        Tcl_AlertNotifierProc *alertNotifierProc;
        Tcl_ServiceModeHookProc *serviceModeHookProc;
    } Tcl_NotifierProcs;

Tcl_SetNotifier への呼出しに続いて､ Tcl_NotifierProcs 構造内で与えられた指示子は､なんであれ､処理課程内に実装された告知譜を置換える｡ Following the call to Tcl_SetNotifier, the pointers given in the Tcl_NotifierProcs structure replace whatever notifier had been installed in the process.

動いている告知譜の置換えは異常に分別がない｡通常､Tcl_SetNotifier は Tcl_InitNotifier への最初の呼出しの前の処理課程の初期化時間に呼出すべきである｡ It is extraordinarily unwise to replace a running notifier. Normally, Tcl_SetNotifier should be called at process initialization time before the first call to Tcl_InitNotifier.

### EXTERNAL EVENT LOOPS

告知譜対話機能は Tcl が､それ自身の私的行事巡回を有する応用譜内に埋込みできる様に設計されている｡この場合､応用譜は Tcl_DoOneEvent を呼出さない､但し､Tcl update､又は vwait の如く､再帰的行事巡回の場合を除く｡大多数の時間は応用譜内の外部行事巡回内で消費される｡この場合､この告知譜は種々の Tcl 行事源資上で何かが起る時に Tcl 内に呼戻す為の外部行事巡回の為に手配しなければならない｡これらの呼戻しは適切な Tcl 行事が､ Tcl 行事待ち行列上に置かれる様に手配するべきである｡ The notifier interfaces are designed so that Tcl can be embedded into applications that have their own private event loops. In this case, the application does not call Tcl_DoOneEvent except in the case of recursive event loops such as calls to the Tcl commands update or vwait. Most of the time is spent in the external event loop of the application. In this case the notifier must arrange for the external event loop to call back into Tcl when something happens on the various Tcl event sources. These callbacks should arrange for appropriate Tcl events to be placed on the Tcl event queue.

通常の基礎上では､外部行事巡回が Tcl_DoOneEvent を呼ばないので､何時であれ行事が Tcl 行事待ち行列上で仕掛かっている時は Tcl_ServiceEvent が呼出される様に段取りすることは告知譜次第である｡これを行う最も簡単な方法は､外部行事巡回からのそれぞれの呼戻しの終った時に Tcl_ServiceAll を起動することである｡これは､応用譜に制御を返す前に､全ての行事源資が巡回され､どの待ち行列の行事も役務処理され､どの仕掛かり空転処理機能も処理されていることを確実にする｡更に､行事の為に巡回する必要のある行事源資は､外部行事巡回に､縦え系の行事待ち行列上で利用できる行事がなくても Tcl を呼出すことを強制する為に Tcl_SetMaxBlockTime を呼ぶことができる｡ Because the external event loop is not calling Tcl_DoOneEvent on a regular basis, it is up to the notifier to arrange for Tcl_ServiceEvent to be called whenever events are pending on the Tcl event queue. The easiest way to do this is to invoke Tcl_ServiceAll at the end of each callback from the external event loop. This will ensure that all of the event sources are polled, any queued events are serviced, and any pending idle handlers are processed before returning control to the application. In addition, event sources that need to poll for events can call Tcl_SetMaxBlockTime to force the external event loop to call Tcl even if no events are available on the system event queue.

主外部行事巡回内で検出された行事の処理の副作用の為に､Tcl は vwait の様な命令内の再帰的行事巡回を開始する為に Tcl_DoOneEvent を起動できる｡Tcl_DoOneEvent は外部行事巡回を起動する､それは前の段落で記述した様に呼戻しの結果になり､それは､ Tcl_ServiceAll への呼出しの結果になる｡然しながら､これらの場合､ Tcl_ServiceAll 内の行事を役務処理することは望ましくない｡行事の役務処理は必要ではない､理由は､制御はすぐさま外部行事巡回に戻り､そこで Tcl_DoOneEvent に戻る､それは行事自身を処理できる｡更に､Tcl_DoOneEvent はただ一つの行事のみ処理すると仮定されている､そこで､ Tcl_ServiceAll は通常全ての仕掛の行事を役務処理する｡この状態を扱う為に､ Tcl_DoOneEvent は Tcl_ServiceAll の為に旗印を設定する､それは､どの行事も役務処理することなく帰ることを惹き起こす｡この旗印は役務処理様式と呼ばれる; Tcl_DoOneEvent はそれが帰る前に以前の値を再貯蔵する｡ As a side effect of processing events detected in the main external event loop, Tcl may invoke Tcl_DoOneEvent to start a recursive event loop in commands like vwait. Tcl_DoOneEvent will invoke the external event loop, which will result in callbacks as described in the preceding paragraph, which will result in calls to Tcl_ServiceAll. However, in these cases it is undesirable to service events in Tcl_ServiceAll. Servicing events there is unnecessary because control will immediately return to the external event loop and hence to Tcl_DoOneEvent, which can service the events itself. Furthermore, Tcl_DoOneEvent is supposed to service only a single event, whereas Tcl_ServiceAll normally services all pending events. To handle this situation, Tcl_DoOneEvent sets a flag for Tcl_ServiceAll that causes it to return without servicing any events. This flag is called the service mode; Tcl_DoOneEvent restores it to its previous value before it returns.

ある場合には､然しながら､縦え Tcl_DoOneEvent から起動された時でも Tcl_ServiceAll の為に行事を役務処理するに必要があるかもしれない｡この事は､ Tcl_DoOneEvent によって呼出された行事操作子に経由で起動された､他の再帰的行事巡回が､未だ､存在する時に生じる(元来の部品の部分のものの如くに)｡この場合､ Tcl_DoOneEvent は行事に役務処理させる機会がないかもしれず､そこで､ Tcl_ServiceAll はそれ全てを処理しなければならない｡Tcl_DoOneEvent よりも､外部行事巡回を呼出す､どの再帰的行事巡回も役務様式を再設定しなければならないので､全ての行事は Tcl_ServiceAll 内で処理される｡この事は､ Tcl_SetServiceMode 手続函数の起動により遂行される｡もし Tcl_SetServiceMode が TCL_SERVICE_NONE に渡されると､Tcl_ServiceAll への呼出しは､どの行事も処理することなくすぐさま帰る｡もし Tcl_SetServiceMode が TCL_SERVICE_ALL に渡されると､ Tcl_ServiceAll の呼出しは通常に振舞う｡Tcl_SetServiceMode は役務処理様式の以前の値を返す､それは再帰的巡回が終了した時に再貯蔵されるべきである｡Tcl_GetServiceMode は役務処理様式の現在の値を返す｡ In some cases, however, it may be necessary for Tcl_ServiceAll to service events even when it has been invoked from Tcl_DoOneEvent. This happens when there is yet another recursive event loop invoked via an event handler called by Tcl_DoOneEvent (such as one that is part of a native widget). In this case, Tcl_DoOneEvent may not have a chance to service events so Tcl_ServiceAll must service them all. Any recursive event loop that calls an external event loop rather than Tcl_DoOneEvent must reset the service mode so that all events get processed in Tcl_ServiceAll. This is done by invoking the Tcl_SetServiceMode procedure. If Tcl_SetServiceMode is passed TCL_SERVICE_NONE, then calls to Tcl_ServiceAll will return immediately without processing any events. If Tcl_SetServiceMode is passed TCL_SERVICE_ALL, then calls to Tcl_ServiceAll will behave normally. Tcl_SetServiceMode returns the previous value of the service mode, which should be restored when the recursive loop exits. Tcl_GetServiceMode returns the current value of the service mode.

### SEE ALSO

Tcl_CreateFileHandler, Tcl_DeleteFileHandler, Tcl_Sleep, Tcl_DoOneEvent, Thread

### KEYWORDS

event, notifier, event queue, event sources, file events, timer, idle, service mode, threads
Copyright © 1998-1999 Scriptics Corporation
Copyright © 1995-1997 Sun Microsystems, Inc.