tip#511 proposed implementation

1 files changed, 23 insertions, 12 deletions

diff --git a/doc/Async.3 b/doc/Async.3
index 347ba3d..e6ec5f8 100644
--- a/doc/Async.3
+++ b/doc/Async.3
@@ -9,7 +9,7 @@
 .so man.macros
 .BS
 .SH NAME
-Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
+Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncMarkFromSignal, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady \- handle asynchronous events
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -17,11 +17,16 @@ Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete, Tcl_AsyncReady
 Tcl_AsyncHandler
 \fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
 .sp
+void
 \fBTcl_AsyncMark\fR(\fIasync\fR)
 .sp
 int
+\fBTcl_AsyncMarkFromSignal\fR(\fIasync\fR, \fIsigNumber\fR)
+.sp
+int
 \fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
 .sp
+void
 \fBTcl_AsyncDelete\fR(\fIasync\fR)
 .sp
 int
@@ -34,6 +39,8 @@ Procedure to invoke to handle an asynchronous event.
 One-word value to pass to \fIproc\fR.
 .AP Tcl_AsyncHandler async in
 Token for asynchronous event handler.
+.AP int sigNumber in
+POSIX signal number, when used in a signal context.
 .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
@@ -60,10 +67,11 @@ 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.
+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_AsyncMarkFromSignal\fR
+or \fBTcl_AsyncMark\fR with this token will only yield the origin
+thread into the asynchronous handler.
 .PP
 \fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
 a token for it.
@@ -72,13 +80,16 @@ 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.
+(such as a POSIX signal handler) should call \fBTcl_AsyncMarkFromSignal\fR
+with the token for the handler and the POSIX signal number. The
+return value of this function is true, when the handler will be
+marked, false otherwise.
+For non-signal contexts, \fBTcl_AsyncMark\fR serves the same purpose.
+\fBTcl_AsyncMarkFromSignal\fR and \fBTcl_AsyncMark\fR will mark
+the handler as ready to execute, but 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