From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Paul Eggert Newsgroups: gmane.emacs.devel Subject: [PATCH 3/7] Doc patches for ns-resolution time stamps Date: Fri, 01 Jul 2011 01:15:07 -0700 Organization: UCLA Computer Science Department Message-ID: <4E0D820B.9070906@cs.ucla.edu> References: <4E0D704F.4070304@cs.ucla.edu> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1309509133 10067 80.91.229.12 (1 Jul 2011 08:32:13 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Fri, 1 Jul 2011 08:32:13 +0000 (UTC) To: Emacs Development Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Jul 01 10:32:09 2011 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1QcZ8y-0002r7-Ka for ged-emacs-devel@m.gmane.org; Fri, 01 Jul 2011 10:32:08 +0200 Original-Received: from localhost ([::1]:59028 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QcZ8x-0001Mk-8e for ged-emacs-devel@m.gmane.org; Fri, 01 Jul 2011 04:32:07 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:56333) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QcYsa-0005M7-Du for emacs-devel@gnu.org; Fri, 01 Jul 2011 04:15:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QcYsY-0001KF-5z for emacs-devel@gnu.org; Fri, 01 Jul 2011 04:15:11 -0400 Original-Received: from smtp.cs.ucla.edu ([131.179.128.62]:45693) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QcYsX-0001Jn-Jn for emacs-devel@gnu.org; Fri, 01 Jul 2011 04:15:09 -0400 Original-Received: from localhost (localhost.localdomain [127.0.0.1]) by smtp.cs.ucla.edu (Postfix) with ESMTP id C1CD939E8106 for ; Fri, 1 Jul 2011 01:15:08 -0700 (PDT) X-Virus-Scanned: amavisd-new at smtp.cs.ucla.edu Original-Received: from smtp.cs.ucla.edu ([127.0.0.1]) by localhost (smtp.cs.ucla.edu [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id AD9a38hUkg37 for ; Fri, 1 Jul 2011 01:15:08 -0700 (PDT) Original-Received: from [192.168.1.10] (pool-71-189-109-235.lsanca.fios.verizon.net [71.189.109.235]) by smtp.cs.ucla.edu (Postfix) with ESMTPSA id 060BF39E80F2 for ; Fri, 1 Jul 2011 01:15:08 -0700 (PDT) User-Agent: Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.2.17) Gecko/20110516 Thunderbird/3.1.10 In-Reply-To: <4E0D704F.4070304@cs.ucla.edu> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 131.179.128.62 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:141331 Archived-At: Document the change to nanosecond-resolution time stamps. * os.texi (Time of Day, Time Parsing, Processor Run Time) (Idle Timers): * processes.texi (System Processes): Time stamp resolution is now nanosecond, not microsecond. === modified file 'doc/lispref/os.texi' --- doc/lispref/os.texi 2011-06-03 18:49:33 +0000 +++ doc/lispref/os.texi 2011-07-01 05:24:03 +0000 @@ -1111,7 +1111,7 @@ as the times obtained from @code{current-time} (see below) and from @code{file-attributes} (@pxref{Definition of file-attributes}). It should be a list whose first two elements are integers; a third -(microsecond) element, if present, is ignored. @var{time-value} can +(nanosecond) element, if present, is ignored. @var{time-value} can also be a cons of two integers, but this usage is obsolete. @example @@ -1124,7 +1124,7 @@ @defun current-time This function returns the system's time value as a list of three -integers: @code{(@var{high} @var{low} @var{microsec})}. The integers +numbers: @code{(@var{high} @var{low} @var{nanosec})}. The numbers @var{high} and @var{low} combine to give the number of seconds since 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is @ifnottex @@ -1134,11 +1134,14 @@ $high*2^{16}+low$. @end tex -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). - -The first two elements can be compared with file time values such as you +The third number, @var{nanosec}, gives the nanoseconds since the +start of the current second. It may have trailing zeros on systems +that return time with lower resolutions. + +The numbers are normally integers, but they are floating-point numbers +if they are outside the integer range. + +The list can be compared with file time values such as you get with the function @code{file-attributes}. @xref{Definition of file-attributes}. @end defun @@ -1340,8 +1343,6 @@ This stands for the nanoseconds (000000000-999999999). To ask for fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for microseconds, etc. Any excess digits are discarded, without rounding. -Currently Emacs time stamps are at best microsecond resolution so the -last three digits generated by plain @samp{%N} are always zero. @item %p This stands for @samp{AM} or @samp{PM}, as appropriate. @item %r @@ -1493,18 +1494,8 @@ @defun get-internal-run-time This function returns the processor run time used by Emacs as a list -of three integers: @code{(@var{high} @var{low} @var{microsec})}. The -integers @var{high} and @var{low} combine to give the number of -seconds, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds (or 0 for -systems that return time with the resolution of only one second). +of three numbers: @code{(@var{high} @var{low} @var{nanosec})}, using +the same format as @code{current-time} (@pxref{Time of Day}). Note that the time returned by this function excludes the time Emacs was not using the processor, and if the Emacs process has several @@ -1748,19 +1739,9 @@ @c Emacs 19 feature @defun current-idle-time If Emacs is idle, this function returns the length of time Emacs has -been idle, as a list of three integers: @code{(@var{high} @var{low} -@var{microsec})}. The integers @var{high} and @var{low} combine to -give the number of seconds of idleness, which is -@ifnottex -@var{high} * 2**16 + @var{low}. -@end ifnottex -@tex -$high*2^{16}+low$. -@end tex - -The third element, @var{microsec}, gives the microseconds since the -start of the current second (or 0 for systems that return time with -the resolution of only one second). +been idle, as a list of three numbers: @code{(@var{high} @var{low} +@var{nanosec})}, using the same format as @code{current-time} +(@pxref{Time of Day}). When Emacs is not idle, @code{current-idle-time} returns @code{nil}. This is a convenient way to test whether Emacs is idle. === modified file 'doc/lispref/processes.texi' --- doc/lispref/processes.texi 2011-06-15 17:30:41 +0000 +++ doc/lispref/processes.texi 2011-07-01 05:24:03 +0000 @@ -1770,7 +1770,7 @@ @item utime Time spent by the process in the user context, for running the application's code. The corresponding @var{value} is in the -@w{@code{(@var{high} @var{low} @var{microsec})}} format, the same +@w{@code{(@var{high} @var{low} @var{nanosec})}} format, the same format used by functions @code{current-time} (@pxref{Time of Day, current-time}) and @code{file-attributes} (@pxref{File Attributes}). @@ -1801,12 +1801,12 @@ @item start The time when the process was started, in the same -@w{@code{(@var{high} @var{low} @var{microsec})}} format used by +@w{@code{(@var{high} @var{low} @var{nanosec})}} format used by @code{current-time} and @code{file-attributes}. @item etime The time elapsed since the process started, in the @w{@code{(@var{high} -@var{low} @var{microsec})}} format. +@var{low} @var{nanosec})}} format. @item vsize The virtual memory size of the process, measured in kilobytes.