summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorandreas_kupries <akupries@shaw.ca>2005-01-21 22:24:43 (GMT)
committerandreas_kupries <akupries@shaw.ca>2005-01-21 22:24:43 (GMT)
commitf11befd3bbce6f1f7a8cd43bb51bf6126ba125bf (patch)
tree403c7dfd1bf849fa476cb6ccaf3a2231eaca625a /doc
parent2587836dd5f442ad7f95eb68cd40e56545b72663 (diff)
downloadtcl-f11befd3bbce6f1f7a8cd43bb51bf6126ba125bf.zip
tcl-f11befd3bbce6f1f7a8cd43bb51bf6126ba125bf.tar.gz
tcl-f11befd3bbce6f1f7a8cd43bb51bf6126ba125bf.tar.bz2
* generic/tclStubInit.c: Regenerated the stubs support code from
* generic/tclDecls.h: the modified tcl.decls (TIP #233, see below). * doc/GetTime.3: Implemented TIP #233, i.e. the * generic/tcl.decls: 'Virtualization of Tcl's Sense of Time'. * generic/tcl.h: Declared, implemented, and documented the * generic/tclInt.h: specified new API functions. Moved the * unix/tclUnixEvent.c: native (OS) access to time information * unix/tclUnixNotfy.c: into standard handler functions. Inserted * unix/tclUnixTime.c: hooks calling on the handlers where native * win/tclWinNotify.c: access was done before, and where scaling * win/tclWinTime.c: between domains (real/virtual) is required.
Diffstat (limited to 'doc')
-rw-r--r--doc/GetTime.349
1 files changed, 49 insertions, 0 deletions
diff --git a/doc/GetTime.3 b/doc/GetTime.3
index 7941379..22ffc53 100644
--- a/doc/GetTime.3
+++ b/doc/GetTime.3
@@ -16,10 +16,33 @@ Tcl_GetTime \- get date and time
\fB#include <tcl.h>\fR
.sp
\fBTcl_GetTime\fR(\fItimePtr\fR)
+.sp
+\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
+.sp
+\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
.SH ARGUMENTS
.AS "Tcl_Time *" timePtr out
.AP "Tcl_Time *" timePtr out
Points to memory in which to store the date and time information.
+.AS "Tcl_GetTimeProc *" getProc in
+.AP "Tcl_GetTimeProc *" getProc in
+Pointer to handler function replacing Tcl_GetTime's access to the OS.
+.AS "Tcl_ScaleTimeProc *" scaleProc in
+.AP "Tcl_ScaleTimeProc *" scaleProc in
+Pointer to handler function for the conversion of time delays in the
+virtual domain to real-time.
+.AS "ClientData *" clientData in
+.AP "ClientData *" clientData in
+Value passed through to the two handler functions.
+.AS "Tcl_GetTimeProc **" getProcPtr inout
+.AP "Tcl_GetTimeProc **" getProcPtr inout
+Pointer to place the currently registered get handler function into.
+.AS "Tcl_ScaleTimeProc **" scaleProcPtr inout
+.AP "Tcl_ScaleTimeProc **" scaleProcPtr inout
+Pointer to place the currently registered scale handler function into.
+.AS "ClientData **" clientDataPtr inout
+.AP "ClientData **" clientDataPtr inout
+Pointer to place the currently registered pass-through value into.
.BE
.SH DESCRIPTION
.PP
@@ -47,6 +70,32 @@ computer system. On multiprocessor variants of Windows, this number
may be limited to the 10- or 20-ms granularity of the system clock.
(On single-processor Windows systems, the \fIusec\fR field is derived
from a performance counter and is highly precise.)
+.PP
+The \fBTcl_SetTime\fR function registers two related handler functions
+with the core. The first handler function is a replacement for
+\fBTcl_GetTime\fR, or rather the OS access made by
+\fBTcl_GetTime\fR. The other handler function is used by the Tcl
+notifier to convert wait/block times from the virtual domain into real
+time.
+.PP
+The \fBTcl_QueryTime\fR function returns the currently registered
+handler functions. If no external handlers were set then this will
+return the standard handlers accessing and processing the native time
+of the OS. The arguments to the function are allowed to be NULL; and
+any argument which is NULL is ignored and not set.
+.PP
+Any handler pair specified has to return data which is consistent
+between them. In other words, setting one handler of the pair to
+something assuming a 10-times slowdown, and the other handler of the
+pair to something assuming a two-times slowdown is wrong and not
+allowed.
+.PP
+The set handler functions are allowed to run the delivered time
+backwards, however this should be avoided. We have to allow it as the
+native time can run backwards as the user can fiddle with the system
+time one way or other. Note that the insertion of the hooks will not
+change the behaviour of the Tcl core with regard to this situation,
+i.e. the existing behaviour is retained.
.SH "SEE ALSO"
clock
.SH KEYWORDS