Doc fixes for timer.el (Bug#8793).

[bpt/emacs.git] / lisp / emacs-lisp / timer.el

diff --git a/lisp/emacs-lisp/timer.el b/lisp/emacs-lisp/timer.el
index 6ae6a86..0a03517 100644 (file)
--- a/lisp/emacs-lisp/timer.el
+++ b/lisp/emacs-lisp/timer.el
@@ -1,7 +1,6 @@
 ;;; timer.el --- run a function with args at some time in future
 
-;; Copyright (C) 1996, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
-;;   2009, 2010  Free Software Foundation, Inc.
+;; Copyright (C) 1996, 2001-2011  Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
 ;; Package: emacs
@@ -93,31 +92,20 @@ fire each time Emacs is idle for that many seconds."
 More precisely, the next value, after TIME, that is an integral multiple
 of SECS seconds since the epoch.  SECS may be a fraction."
   (let ((time-base (ash 1 16)))
-    (if (fboundp 'atan)
-       ;; Use floating point, taking care to not lose precision.
-       (let* ((float-time-base (float time-base))
-              (million 1000000.0)
-              (time-usec (+ (* million
-                               (+ (* float-time-base (nth 0 time))
-                                  (nth 1 time)))
-                            (nth 2 time)))
-              (secs-usec (* million secs))
-              (mod-usec (mod time-usec secs-usec))
-              (next-usec (+ (- time-usec mod-usec) secs-usec))
-              (time-base-million (* float-time-base million)))
-         (list (floor next-usec time-base-million)
-               (floor (mod next-usec time-base-million) million)
-               (floor (mod next-usec million))))
-      ;; Floating point is not supported.
-      ;; Use integer arithmetic, avoiding overflow if possible.
-      (let* ((mod-sec (mod (+ (* (mod time-base secs)
-                                (mod (nth 0 time) secs))
-                             (nth 1 time))
-                          secs))
-            (next-1-sec (+ (- (nth 1 time) mod-sec) secs)))
-       (list (+ (nth 0 time) (floor next-1-sec time-base))
-             (mod next-1-sec time-base)
-             0)))))
+    ;; Use floating point, taking care to not lose precision.
+    (let* ((float-time-base (float time-base))
+          (million 1000000.0)
+          (time-usec (+ (* million
+                           (+ (* float-time-base (nth 0 time))
+                              (nth 1 time)))
+                        (nth 2 time)))
+          (secs-usec (* million secs))
+          (mod-usec (mod time-usec secs-usec))
+          (next-usec (+ (- time-usec mod-usec) secs-usec))
+          (time-base-million (* float-time-base million)))
+      (list (floor next-usec time-base-million)
+           (floor (mod next-usec time-base-million) million)
+           (floor (mod next-usec million))))))
 
 (defun timer-relative-time (time secs &optional usecs)
   "Advance TIME by SECS seconds and optionally USECS microseconds.
@@ -201,35 +189,35 @@ fire repeatedly that many seconds apart."
              (setcdr reuse-cell timers))
          (setq reuse-cell (cons timer timers)))
        ;; Insert new timer after last which possibly means in front of queue.
-       (if last
-           (setcdr last reuse-cell)
-          (if idle
-              (setq timer-idle-list reuse-cell)
-            (setq timer-list reuse-cell)))
+       (cond (last (setcdr last reuse-cell))
+             (idle (setq timer-idle-list reuse-cell))
+             (t    (setq timer-list reuse-cell)))
        (setf (timer--triggered timer) triggered-p)
        (setf (timer--idle-delay timer) idle)
        nil)
     (error "Invalid or uninitialized timer")))
 
-(defun timer-activate (timer &optional triggered-p reuse-cell idle)
-  "Put TIMER on the list of active timers.
+(defun timer-activate (timer &optional triggered-p reuse-cell)
+  "Insert TIMER into `timer-list'.
+If TRIGGERED-P is t, make TIMER inactive (put it on the list, but
+mark it as already triggered).  To remove it, use `cancel-timer'.
 
-If TRIGGERED-P is t, that means to make the timer inactive
-\(put it on the list, but mark it as already triggered).
-To remove from the list, use `cancel-timer'.
-
-REUSE-CELL, if non-nil, is a cons cell to reuse instead
-of allocating a new one."
+REUSE-CELL, if non-nil, is a cons cell to reuse when inserting
+TIMER into `timer-list' (usually a cell removed from that list by
+`cancel-timer-internal'; using this reduces consing for repeat
+timers).  If nil, allocate a new cell."
   (timer--activate timer triggered-p reuse-cell nil))
 
 (defun timer-activate-when-idle (timer &optional dont-wait reuse-cell)
-  "Arrange to activate TIMER whenever Emacs is next idle.
-If optional argument DONT-WAIT is non-nil, then enable the
-timer to activate immediately, or at the right time, if Emacs
-is already idle.
-
-REUSE-CELL, if non-nil, is a cons cell to reuse instead
-of allocating a new one."
+  "Insert TIMER into `timer-idle-list'.
+This arranges to activate TIMER whenever Emacs is next idle.
+If optional argument DONT-WAIT is non-nil, set TIMER to activate
+immediately, or at the right time, if Emacs is already idle.
+
+REUSE-CELL, if non-nil, is a cons cell to reuse when inserting
+TIMER into `timer-idle-list' (usually a cell removed from that
+list by `cancel-timer-internal'; using this reduces consing for
+repeat timers).  If nil, allocate a new cell."
   (timer--activate timer (not dont-wait) reuse-cell 'idle))
 
 (defalias 'disable-timeout 'cancel-timer)
@@ -543,5 +531,4 @@ If the user does not answer after SECONDS seconds, return DEFAULT-VALUE."
 \f
 (provide 'timer)
 
-;; arch-tag: b1a9237b-7787-4382-9e46-8f2c3b3273e0
 ;;; timer.el ends here