[q-lang-cvs] q/doc qdoc.texi,1.147,1.148 version.texi,1.99,1.100

[Albert G. <ag...@us...>]

Update of /cvsroot/q-lang/q/doc
In directory sc8-pr-cvs16.sourceforge.net:/tmp/cvs-serv22963

Modified Files:
	qdoc.texi version.texi 
Log Message:
update documentation

Index: qdoc.texi
===================================================================
RCS file: /cvsroot/q-lang/q/doc/qdoc.texi,v
retrieving revision 1.147
retrieving revision 1.148
diff -C2 -d -r1.147 -r1.148
*** qdoc.texi	22 Feb 2008 09:31:24 -0000	1.147
--- qdoc.texi	23 Feb 2008 09:39:24 -0000	1.148
***************
*** 14198,14204 ****
  the @code{system} module) are used to return information about the
  active timezone and the current time, and convert time values to various
! formats. Also available are functions to measure cpu time. These
! functions are in close correspondence with the date and time functions
! of the C library.
  
  The calendar date and time functions use two different representations
--- 14198,14204 ----
  the @code{system} module) are used to return information about the
  active timezone and the current time, and convert time values to various
! formats. Also available are functions to measure cpu time and
! high-resolution timers. These functions are in close correspondence with
! the date and time functions of the C library.
  
  The calendar date and time functions use two different representations
***************
*** 14289,14292 ****
--- 14289,14294 ----
  @end smallexample
  
+ @subheading Measuring CPU Time
+ 
  Two additional functions are provided for measuring cpu time. Note that
  @code{clock} and @code{times} measure cpu time in different units, given
***************
*** 14320,14323 ****
--- 14322,14408 ----
  approximately every 72 minutes.
  
+ @subheading High-Resolution Timers
+ 
+ On systems where the POSIX 1003.1-2001 timer extension is available (at
+ the time of this writing, this comprises most recent Linux and Unix
+ systems, but not Windows), the @code{system} module provides a number of
+ operations to deal with high-resolution timers. These will be useful for
+ realtime applications and other programs with strict timing
+ requirements.
+ 
+ @findex nanotime
+ @findex nanores
+ @findex nanosleep
+ @findex nanosleep_until
+ @smallexample
+ public extern nanotime ID, nanores ID;
+ public extern nanosleep ID T, nanosleep_until ID T;
+ @end smallexample
+ 
+ Note that these operations differ from the builtin @code{time} and
+ @code{sleep} functions (see @ref{Miscellaneous Functions}) in that they
+ use integer (unsigned 64 bit) time values specified in nanoseconds. The
+ @code{nanotime} function returns the current time in nanosecs, the
+ @code{nanores} function the resolution of the given timer (i.e., the
+ smallest measurable amount of time in nanosecs). The @code{nanosleep}
+ function sleeps for the specified amount of nanoseconds, while the
+ @code{nanosleep_until} function sleeps until the given (absolute) time
+ arrives. In case of any internal error condition, these functions will
+ set @code{errno} accordingly.
+ 
+ Just like the @code{sleep} function, the @code{nanosleep} and
+ @code{nanosleep_until} functions may wake up early if a signal is
+ delivered to the process. In this case @code{errno} will be set to
+ @code{EINTR}, and @code{nanosleep} will return the remaining time until
+ the planned wakeup, while @code{nanosleep_until} will simply fail. If
+ the sleep terminates normally, @code{nanosleep} will return zero and
+ @code{nanosleep_until} @code{()}, respectively.
+ 
+ For each of the functions you have to specify an integer-valued timer
+ id. In the current implementation, the following timers are supported:
+ 
+ @itemize @bullet
+ @item
+ @code{CLOCK_REALTIME}: The system clock, measured in nanosecs since the
+ epoch. This will be the same time as returned by the builtin @code{time}
+ function (up to rounding issues with the latter).
+ @item
+ @code{CLOCK_MONOTONIC}: Monotonic (non-decreasing) time since some
+ unspecified starting point. This clock cannot be reset by the user and
+ is thus to be preferred in realtime applications.
+ @item
+ @code{CLOCK_PROCESS_CPUTIME}, @code{CLOCK_THREAD_CPUTIME}: Highres
+ per-process and per-thread CPU timers. (Normally these are for timing
+ purposes only and might be unreliable on SMP systems, see
+ @code{clock_gettime}(3) for details.)
+ @end itemize
+ 
+ Only @code{CLOCK_REALTIME} is guaranteed to exist (on systems which
+ implement the highres timers at all, that is). If a given clock is
+ unavailable on the host system, the corresponding id will be @code{()}.
+ (If @code{CLOCK_REALTIME} is @code{()} then the highres timers are not
+ supported at all.)
+ 
+ Moreover, if CPU timers are available, then the following
+ @code{process_cpu_clockid} and @code{thread_cpu_clockid} functions can
+ be used to return the clock id for the given process id (0 denotes the
+ current process) and the given thread, respectively:
+ 
+ @findex process_cpu_clockid
+ @findex thread_cpu_clockid
+ @smallexample
+ public extern process_cpu_clockid PID, thread_cpu_clockid THREAD;
+ @end smallexample
+ 
+ CAVEAT: While the highres timers nominally support nanoseconds
+ resolution, the actual resolutions depend on your system setup and will
+ typically be much coarser (for the system and monotonic clocks, they are
+ usually in the milliseconds range on current PCs). Also, be aware that
+ there are system latencies which might cause calls to @code{nanosleep}
+ and @code{nanosleep_until} to wake up late. You can use realtime
+ scheduling priorities to mitigate these effects to some extent, see
+ @ref{Realtime Scheduling}, but some sources of latency will still
+ remain.
+ 
  @node Internationalization, Filename Globbing, Time Functions, Clib
  @section Internationalization

Index: version.texi
===================================================================
RCS file: /cvsroot/q-lang/q/doc/version.texi,v
retrieving revision 1.99
retrieving revision 1.100
diff -C2 -d -r1.99 -r1.100
*** version.texi	22 Feb 2008 09:31:24 -0000	1.99
--- version.texi	23 Feb 2008 09:39:24 -0000	1.100
***************
*** 1,3 ****
! @set UPDATED 22 February 2008
  @set UPDATED-MONTH February 2008
  @set EDITION 7.11
--- 1,3 ----
! @set UPDATED 23 February 2008
  @set UPDATED-MONTH February 2008
  @set EDITION 7.11