undo subtree

1 files changed, 0 insertions, 161 deletions

diff --git a/tcl8.6/doc/Async.3 b/tcl8.6/doc/Async.3
deleted file mode 100644
index 347ba3d..0000000
--- a/tcl8.6/doc/Async.3
+++ /dev/null
@@ -1,161 +0,0 @@
-'\"
-'\" Copyright (c) 1989-1993 The Regents of the University of California.
-'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
-'\"
-'\" See the file "license.terms" for information on usage and redistribution
-'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
-.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
-.so man.macros
-.BS
-.SH NAME
-Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
-.SH SYNOPSIS
-.nf
-\fB#include <tcl.h>\fR
-.sp
-Tcl_AsyncHandler
-\fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
-.sp
-\fBTcl_AsyncMark\fR(\fIasync\fR)
-.sp
-int
-\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
-.sp
-\fBTcl_AsyncDelete\fR(\fIasync\fR)
-.sp
-int
-\fBTcl_AsyncReady\fR()
-.SH ARGUMENTS
-.AS Tcl_AsyncHandler clientData
-.AP Tcl_AsyncProc *proc in
-Procedure to invoke to handle an asynchronous event.
-.AP ClientData clientData in
-One-word value to pass to \fIproc\fR.
-.AP Tcl_AsyncHandler async in
-Token for asynchronous event handler.
-.AP Tcl_Interp *interp in
-Tcl interpreter in which command was being evaluated when handler was
-invoked, or NULL if handler was invoked when there was no interpreter
-active.
-.AP int code in
-Completion code from command that just completed in \fIinterp\fR,
-or 0 if \fIinterp\fR is NULL.
-.BE
-
-.SH DESCRIPTION
-.PP
-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.
-.PP
-\fBTcl_AsyncCreate\fR, \fBTcl_AsyncDelete\fR, and \fBTcl_AsyncReady\fR
-are thread sensitive.  They access and/or set a thread-specific data
-structure in the event of a core built with \fI\-\-enable\-threads\fR.  The token
-created by \fBTcl_AsyncCreate\fR contains the needed thread information it
-was called from so that calling \fBTcl_AsyncMark\fR(\fItoken\fR) will only yield
-the origin thread into the asynchronous handler.
-.PP
-\fBTcl_AsyncCreate\fR 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 \fBTcl_AsyncMark\fR with the
-token for the handler.
-\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
-will not invoke the handler immediately.
-Tcl will call the \fIproc\fR associated with the handler later, when
-the world is in a safe state, and \fIproc\fR can then carry out
-the actions associated with the asynchronous event.
-\fIProc\fR should have arguments and result that match the
-type \fBTcl_AsyncProc\fR:
-.PP
-.CS
-typedef int \fBTcl_AsyncProc\fR(
-        ClientData \fIclientData\fR,
-        Tcl_Interp *\fIinterp\fR,
-        int \fIcode\fR);
-.CE
-.PP
-The \fIclientData\fR will be the same as the \fIclientData\fR
-argument passed to \fBTcl_AsyncCreate\fR when the handler was
-created.
-If \fIproc\fR is invoked just after a command has completed
-execution in an interpreter, then \fIinterp\fR will identify
-the interpreter in which the command was evaluated and
-\fIcode\fR will be the completion code returned by that
-command.
-The command's result will be present in the interpreter's result.
-When \fIproc\fR returns, whatever it leaves in the interpreter's result
-will be returned as the result of the command and the integer
-value returned by \fIproc\fR will be used as the new completion
-code for the command.
-.PP
-It is also possible for \fIproc\fR 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 \fIinterp\fR will be NULL and \fIcode\fR will be
-0, and the return value from \fIproc\fR will be ignored.
-.PP
-The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
-handlers that are ready.
-The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
-asynchronous handlers are ready;  it can be checked to avoid calls
-to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
-Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
-and calls \fBTcl_AsyncInvoke\fR if needed.
-Applications may also call \fBTcl_AsyncInvoke\fR at interesting
-times for that application.
-For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
-after each event and calls \fBTcl_AsyncInvoke\fR if needed.
-The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
-have the same meaning as for \fIproc\fR:  they identify the active
-interpreter, if any, and the completion code from the command
-that just completed.
-.PP
-\fBTcl_AsyncDelete\fR removes an asynchronous handler so that
-its \fIproc\fR will never be invoked again.
-A handler can be deleted even when ready, and it will still
-not be invoked.
-.PP
-If multiple handlers become active at the same time, the
-handlers are invoked in the order they were created (oldest
-handler first).
-The \fIcode\fR 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,
-\fBTcl_AsyncInvoke\fR 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.
-.SH WARNING
-.PP
-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 \fIcode\fR 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
-\fBTcl_SaveInterpState\fR, passing in the \fIcode\fR argument.
-When the asynchronous handler is finished it should restore
-the interpreter's state by calling \fBTcl_RestoreInterpState\fR,
-and then returning the \fIcode\fR argument.
-
-.SH KEYWORDS
-asynchronous event, handler, signal, Tcl_SaveInterpState, thread