## Tcl8.6.17/Tk8.6.17 Documentation > Tcl C API > Async

### 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_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady — 非同期行事の処理 handle asynchronous events
  SYNOPSIS
    #include <tcl.h>
    Tcl_AsyncHandler
    Tcl_AsyncCreate(proc, clientData)
    void
    Tcl_AsyncMark(async)
    int
    Tcl_AsyncInvoke(interp, code)
    void
    Tcl_AsyncDelete(async)
    int
    Tcl_AsyncReady()
  引数 ARGUMENTS
    Tcl_AsyncProc *proc (入力in)
    ClientData clientData (入力in)
    Tcl_AsyncHandler async (入力in)
    Tcl_Interp *interp (入力in)
    int code (入力in)
  説明 DESCRIPTION
  警告 WARNING
  KEYWORDS

### NAME

Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady — 非同期行事の処理 handle asynchronous events

### SYNOPSIS

#include <tcl.h>
Tcl_AsyncHandler
Tcl_AsyncCreate(proc, clientData)
void
Tcl_AsyncMark(async)
int
Tcl_AsyncInvoke(interp, code)
void
Tcl_AsyncDelete(async)
int
Tcl_AsyncReady()

### 引数 ARGUMENTS

Tcl_AsyncProc *proc (入力in)
  非同期行事を取り扱う為に起動する手続函数｡　 Procedure to invoke to handle an asynchronous event.

ClientData clientData (入力in)
  proc に渡す１語の値｡ One-word value to pass to proc.

Tcl_AsyncHandler async (入力in)
  非同期行事処理機能の為の字句単位｡ Token for asynchronous event handler.

Tcl_Interp *interp (入力in)
  処理機能が起動された時に命令が評価されるTcl の解釈実行機能､但し､活動状態の解釈実行機能がない時に処理機能が起動されると NULL ｡ 　 Tcl interpreter in which command was being evaluated when handler was invoked, or NULL if handler was invoked when there was no interpreter active.

int code (入力in)
  interp 内で完遂された命令の完了符号､但し､interp が NULL の場合は 0 ｡ 　 Completion code from command that just completed in interp, or 0 if interp is NULL.

### 説明 DESCRIPTION

この手続函数は､信号の様に非同期の行事を扱う安全な仕組みを提供する｡もし信号の様な非同期の行事が Tcl 処理譜が評価されている間に発生した場合､その行事を処理するどのような実質的な行為も安全ではない｡譬えば､ Tcl 記述譜の評価は安全ではない､理由は､解釈実行機能は既に記述譜の評価の途中であるかもしれないから; 記憶域の割付さえも安全ではないかもしれない､理由は行事が発生した時に､記憶域割付の処理の最中であるかもしれないから｡唯一の安全な働きかけは､行事が起ったことを指し示す旗印の設定である､そして譬えば､現在の Tcl 命令が完了した後の如く世界が穏やかな状態に戻った後に行事を処理する｡ 　　 These procedures provide a safe mechanism for dealing with asynchronous events such as signals. If an event such as a signal occurs while a Tcl script is being evaluated then it is not safe to take any substantive action to process the event. For example, it is not safe to evaluate a Tcl script since the interpreter may already be in the middle of evaluating a script; it may not even be safe to allocate memory, since a memory allocation could have been in progress when the event occurred. The only safe approach is to set a flag indicating that the event occurred, then handle the event later when the world has returned to a clean state, such as after the current Tcl command completes.

Tcl_AsyncCreate と Tcl_AsyncDelete と Tcl_AsyncReady は､時分割処理に感受性である｡それらは --enable-threads を伴って機械語翻訳された核の行事内の時分割片固有のデータ構造を利用 及び/又は 設定する｡ Tcl_AsyncCreate によって作成された解析字句はそれが呼出された処に必要な時分割片情報を含むので､ Tcl_AsyncMark (語句解析結果token)の呼出しは非同期処理機能の中に新規の時分割処理をたゞ生成するのみ｡ Tcl_AsyncCreate, Tcl_AsyncDelete, and Tcl_AsyncReady are thread sensitive. They access and/or set a thread-specific data structure in the event of a core built with --enable-threads. The token created by Tcl_AsyncCreate contains the needed thread information it was called from so that calling Tcl_AsyncMark(token) will only yield the origin thread into the asynchronous handler.

Tcl_AsyncCreate は､非同期処理機能を作成しその為の語句解析結果を返す｡非同期処理機能は､処理するように計画されたどのような非同期行事も生成する前に作成されなければならない(行事の瞬間の処理機能作成は安全ではない)｡非同期行事が起った時､行事を検出する符号命令は(譬えば信号処理機能)処理機能の為に語句解析結果と共に Tcl_AsyncMark を呼ぶべきである｡ Tcl_AsyncMark は処理機能に実行の準備完了の印を付けるが処理機能を直接には起動しない｡ Tcl は処理機能に結合した proc を､世界が静寂な状態になった後で､呼出す､proc は非同期行事に結合した活動を実行する｡ proc は Tcl_AsyncProc の型に合致する引数と結果を有する: Tcl_AsyncCreate creates an asynchronous handler and returns a token for it. The asynchronous handler must be created before any occurrences of the asynchronous event that it is intended to handle (it is not safe to create a handler at the time of an event). When an asynchronous event occurs the code that detects the event (such as a signal handler) should call Tcl_AsyncMark with the token for the handler. Tcl_AsyncMark will mark the handler as ready to execute, but it will not invoke the handler immediately. Tcl will call the proc associated with the handler later, when the world is in a safe state, and proc can then carry out the actions associated with the asynchronous event. Proc should have arguments and result that match the type Tcl_AsyncProc:

    typedef int Tcl_AsyncProc(
            ClientData clientData,
            Tcl_Interp *interp,
            int code);

clientData は､処理機能が作成された時に Tcl_AsyncCreate に渡された clientData 引数と同じである｡もし解釈実行機能内で命令が完全に実行が完了した直後に proc が起動された場合､ interp は命令が評価された解釈実行機能を特定し､ code はその命令から返された完了符号である｡その命令の結果は解釈実行機能の結果内に存在する｡ proc が戻るとき､解釈実行機能の結果内に残されたものが何であれ､命令の結果として返され､ proc から返された整数値は命令に関する新しい完了符号として使われる｡ 　　 The clientData will be the same as the clientData argument passed to Tcl_AsyncCreate when the handler was created. If proc is invoked just after a command has completed execution in an interpreter, then interp will identify the interpreter in which the command was evaluated and code will be the completion code returned by that command. The command's result will be present in the interpreter's result. When proc returns, whatever it leaves in the interpreter's result will be returned as the result of the command and the integer value returned by proc will be used as the new completion code for the command.

活動状態の解釈実行機能がない時､ proc の為に起動することは可能である｡これは､譬えば､もし､応用譜が対話的入力又は X 行事を待機している間に非同期行事が起る場合に起りうる｡この場合､ interp はNULL ､符号 code は 0 になり､そして proc の返り値は無視される｡ 　　　 It is also possible for proc to be invoked when no interpreter is active. This can happen, for example, if an asynchronous event occurs while the application is waiting for interactive input or an X event. In this case interp will be NULL and code will be 0, and the return value from proc will be ignored.

手続函数 Tcl_AsyncInvoke は準備ができた全ての処理機能を起動する為に呼出す｡手続函数 Tcl_AsyncReady は何時であれどれかの非同期処理機能が用意できた時に非零を返す; 準備がでた処理機能がない時に Tcl_AsyncInvoke を呼出す事を避ける目的に確認できる｡それぞれの命令が評価された後､ Tcl は Tcl_AsyncReady を呼ぶそして必要なら Tcl_AsyncInvoke を呼ぶ｡応用譜はその応用譜の為に必要な時に Tcl_AsyncInvoke を呼出しても好い｡譬えば､Tcl の行事処理機能はそれぞれの行事の後に Tcl_AsyncReady を呼び､もし必要なら Tcl_AsyncInvoke を呼ぶ｡Tcl_AsyncInvoke の interp と code 引数は proc の為のものと同じ意味を有する: それらは､活動している解釈実行機能を識別する､もしある場合には､丁度完了した命令の完了符号をも識別する｡ 　　 The procedure Tcl_AsyncInvoke is called to invoke all of the handlers that are ready. The procedure Tcl_AsyncReady will return non-zero whenever any asynchronous handlers are ready; it can be checked to avoid calls to Tcl_AsyncInvoke when there are no ready handlers. Tcl calls Tcl_AsyncReady after each command is evaluated and calls Tcl_AsyncInvoke if needed. Applications may also call Tcl_AsyncInvoke at interesting times for that application. For example, Tcl's event handler calls Tcl_AsyncReady after each event and calls Tcl_AsyncInvoke if needed. The interp and code arguments to Tcl_AsyncInvoke have the same meaning as for proc: they identify the active interpreter, if any, and the completion code from the command that just completed.

Tcl_AsyncDelete は､非同期処理機能を取外ので､その proc は二度と起動されなくなる｡処理機能は準備が完了した時にでも取外すことができ､最早起動されなくなる｡ Tcl_AsyncDelete removes an asynchronous handler so that its proc will never be invoked again. A handler can be deleted even when ready, and it will still not be invoked.

もし､複数の処理機能が同時に活性になると､それが作成された順(古い処理機能が先)に起動される｡先の処理機能から返される code と解釈実行機能の結果が後の処理機能に反映されるので､最も最近作成された処理機能が解釈実行機能の結果と完了符合について決定する｡もし処理機能が実行されている間に新しい処理機能処理機能が準備されると､ Tcl_AsyncInvoke はそれら全てを起動する; それぞれの時点で最高の優先順位(古い)の準備できた処理機能を起動し､もはや準備できた処理機能がなくなるまで繰返される｡ 　　　 If multiple handlers become active at the same time, the handlers are invoked in the order they were created (oldest handler first). The code and the interpreter's result for later handlers reflect the values returned by earlier handlers, so that the most recently created handler has last say about the interpreter's result and completion code. If new handlers become ready while handlers are executing, Tcl_AsyncInvoke will invoke them all; at each point it invokes the highest-priority (oldest) ready handler, repeating this over and over until there are no longer any ready handlers.

### 警告 WARNING

非同期行事処理機能に関して解釈実行機能の結果を修正すること､又はその code 引数と異なる符合を返すことは､殆どの場合に最悪の方法である｡この種の挙動は記述譜の実行を微妙な方法で混乱させかねず､窮めて追跡困難な不具合の結果になり得る｡もし非同期行事処理機能が Tcl 記述譜を評価する必要がある場合､最初に Tcl_SaveInterpState を呼出して解釈実行機能の状態を保存し､ code 引数に渡すべきである｡非同期処理機能が終了した時､ Tcl_RestoreInterpState を呼出して解釈実行機能の状態を取戻し､ code 引数に返すべきである｡ 　　 It is almost always a bad idea for an asynchronous event handler to modify the interpreter's result or return a code different from its code argument. This sort of behavior can disrupt the execution of scripts in subtle ways and result in bugs that are extremely difficult to track down. If an asynchronous event handler needs to evaluate Tcl scripts then it should first save the interpreter's state by calling Tcl_SaveInterpState, passing in the code argument. When the asynchronous handler is finished it should restore the interpreter's state by calling Tcl_RestoreInterpState, and then returning the code argument.

### KEYWORDS

asynchronous event, handler, signal, Tcl_SaveInterpState, thread
Copyright © 1989-1993 The Regents of the University of California.
Copyright © 1994-1996 Sun Microsystems, Inc.