summaryrefslogtreecommitdiffstats
path: root/doc/Notifier.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Notifier.3')
-rw-r--r--doc/Notifier.368
1 files changed, 38 insertions, 30 deletions
diff --git a/doc/Notifier.3 b/doc/Notifier.3
index 9edf069..16f9f8d 100644
--- a/doc/Notifier.3
+++ b/doc/Notifier.3
@@ -4,12 +4,12 @@
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
-'\"
+'\"
.TH Notifier 3 8.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH 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 \- the event queue and notifier interfaces
+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
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -81,7 +81,7 @@ queues them.
.AP ClientData clientData in
Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
\fIdeleteProc\fR.
-.AP Tcl_Time *timePtr in
+.AP "const Tcl_Time" *timePtr in
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 \fBTcl_WaitForEvent\fR
@@ -108,7 +108,6 @@ Structure of function pointers describing notifier procedures that are
to replace the ones installed in the executable. See
\fBREPLACING THE NOTIFIER\fR for details.
.BE
-
.SH INTRODUCTION
.PP
The interfaces described here are used to customize the Tcl event
@@ -144,7 +143,7 @@ servicing at a future time. Threaded applications work in a
similar manner, except that there is a separate event queue for
each thread containing a Tcl interpreter.
\fBTcl_QueueEvent\fR is used (primarily
-by event sources) to add events to the event queue and
+by event sources) to add events to the event queue and
\fBTcl_DeleteEvents\fR is used to remove events from the queue without
processing them. In a threaded application, \fBTcl_QueueEvent\fR adds
an event to the current thread's queue, and \fBTcl_ThreadQueueEvent\fR
@@ -215,7 +214,6 @@ return.
.IP [7]
Either return 0 to indicate that no events were ready, or go back to
step [2] if blocking was requested by the caller.
-
.SH "CREATING A NEW EVENT SOURCE"
.PP
An event source consists of three procedures invoked by the notifier,
@@ -229,11 +227,13 @@ The procedure \fBTcl_CreateEventSource\fR creates a new event source.
Its arguments specify the setup procedure and check procedure for
the event source.
\fISetupProc\fR should match the following prototype:
+.PP
.CS
-typedef void Tcl_EventSetupProc(
+typedef void \fBTcl_EventSetupProc\fR(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_CreateEventSource\fR; it is typically used to
point to private information managed by the event source.
@@ -268,12 +268,14 @@ connection.
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
a structure that describes a time interval in seconds and
microseconds:
+.PP
.CS
typedef struct Tcl_Time {
- long \fIsec\fR;
- long \fIusec\fR;
-} Tcl_Time;
+ long \fIsec\fR;
+ long \fIusec\fR;
+} \fBTcl_Time\fR;
.CE
+.PP
The \fIusec\fR field should be less than 1000000.
.PP
Information provided to \fBTcl_SetMaxBlockTime\fR
@@ -303,11 +305,13 @@ The second procedure provided by each event source is its check
procedure, indicated by the \fIcheckProc\fR argument to
\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
following prototype:
+.PP
.CS
-typedef void Tcl_EventCheckProc(
+typedef void \fBTcl_EventCheckProc\fR(
ClientData \fIclientData\fR,
int \fIflags\fR);
.CE
+.PP
The arguments to this procedure are the same as those for \fIsetupProc\fR.
\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
for events. Presumably at least one event source is now prepared to
@@ -326,12 +330,14 @@ to that event source. However, the first element of the structure
must be a structure of type \fBTcl_Event\fR, and the address of this
structure is used when communicating between the event source and the
rest of the notifier. A \fBTcl_Event\fR has the following definition:
+.PP
.CS
typedef struct {
Tcl_EventProc *\fIproc\fR;
struct Tcl_Event *\fInextPtr\fR;
-} Tcl_Event;
+} \fBTcl_Event\fR;
.CE
+.PP
The event source must fill in the \fIproc\fR field of
the event before calling \fBTcl_QueueEvent\fR.
The \fInextPtr\fR is used to link together the events in the queue
@@ -359,11 +365,13 @@ When it is time to handle an event from the queue (steps 1 and 4
above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
in the first queued \fBTcl_Event\fR structure.
\fIProc\fR must match the following prototype:
+.PP
.CS
-typedef int Tcl_EventProc(
+typedef int \fBTcl_EventProc\fR(
Tcl_Event *\fIevPtr\fR,
int \fIflags\fR);
.CE
+.PP
The first argument to \fIproc\fR is a pointer to the event, which will
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
added the event to the queue.
@@ -403,7 +411,7 @@ an event to the current thread's queue.
To add an event to another thread's queue, use \fBTcl_ThreadQueueEvent\fR.
\fBTcl_ThreadQueueEvent\fR 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 \fBTcl_GetCurrentThread\fR
+Tcl_ThreadId for the current thread, use the \fBTcl_GetCurrentThread\fR
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
@@ -416,11 +424,13 @@ events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
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. \fIProc\fR should match the following prototype:
+.PP
.CS
-typedef int Tcl_EventDeleteProc(
+typedef int \fBTcl_EventDeleteProc\fR(
Tcl_Event *\fIevPtr\fR,
ClientData \fIclientData\fR);
.CE
+.PP
The \fIclientData\fR argument will be the same as the \fIclientData\fR
argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
private information managed by the event source. The \fIevPtr\fR will
@@ -430,7 +440,6 @@ point to the next event in the queue.
\fIcheckProc\fR, and \fIclientData\fR arguments must exactly match those
provided to the \fBTcl_CreateEventSource\fR for the event source to be deleted.
If no such source exists, \fBTcl_DeleteEventSource\fR has no effect.
-
.SH "CREATING A NEW NOTIFIER"
.PP
The notifier consists of all the procedures described in this manual
@@ -526,7 +535,6 @@ in their respective manual pages.
The easiest way to create a new notifier is to look at the code
for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
-
.SH "REPLACING THE NOTIFIER"
.PP
A notifier that has been written according to the conventions above
@@ -539,18 +547,20 @@ to another program, such as a Web browser plugin.
To do this, the extension makes a call to \fBTcl_SetNotifier\fR
passing a pointer to a \fBTcl_NotifierProcs\fR data structure. The
structure has the following layout:
+.PP
.CS
typedef struct Tcl_NotifierProcs {
- 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_SetTimerProc *\fIsetTimerProc\fR;
+ Tcl_WaitForEventProc *\fIwaitForEventProc\fR;
+ Tcl_CreateFileHandlerProc *\fIcreateFileHandlerProc\fR;
+ Tcl_DeleteFileHandlerProc *\fIdeleteFileHandlerProc\fR;
+ Tcl_InitNotifierProc *\fIinitNotifierProc\fR;
+ Tcl_FinalizeNotifierProc *\fIfinalizeNotifierProc\fR;
+ Tcl_AlertNotifierProc *\fIalertNotifierProc\fR;
+ Tcl_ServiceModeHookProc *\fIserviceModeHookProc\fR;
+} \fBTcl_NotifierProcs\fR;
.CE
+.PP
Following the call to \fBTcl_SetNotifier\fR, the pointers given in
the \fBTcl_NotifierProcs\fR structure replace whatever notifier had
been installed in the process.
@@ -558,7 +568,6 @@ been installed in the process.
It is extraordinarily unwise to replace a running notifier. Normally,
\fBTcl_SetNotifier\fR should be called at process initialization time
before the first call to \fBTcl_InitNotifier\fR.
-
.SH "EXTERNAL EVENT LOOPS"
.PP
The notifier interfaces are designed so that Tcl can be embedded into
@@ -619,9 +628,8 @@ then calls to \fBTcl_ServiceAll\fR will behave normally.
mode, which should be restored when the recursive loop exits.
\fBTcl_GetServiceMode\fR returns the current value of the service
mode.
-
.SH "SEE ALSO"
-\fBTcl_CreateFileHandler\fR, \fBTcl_DeleteFileHandler\fR, \fBTcl_Sleep\fR,
-\fBTcl_DoOneEvent\fR, \fBThread(3)\fR
+Tcl_CreateFileHandler(3), Tcl_DeleteFileHandler(3), Tcl_Sleep(3),
+Tcl_DoOneEvent(3), Thread(3)
.SH KEYWORDS
event, notifier, event queue, event sources, file events, timer, idle, service mode, threads