do-periodically

Arguments: (seconds &key sleep-first (whostate "sleeping")) &body body)

After evaluating seconds, sleep-first, and whostate (in that order), this macro repeatedly executes body while sleeping for seconds seconds between each execution. It expands into code which roughly produces the following inner loop (the actual macroexpansion is much more complicated):

   (if sleep-first (sleep seconds))
   (loop
      body
      (sleep seconds))

seconds must evaluate to a non-negative real number; sleep-first is a boolean defaulting to nil; whostate must evaluate to a string or nil. whostate defaults to "sleeping".

The purpose of this macro is to reduce consing when executing the same code repeatedly with sleeps in between. Because seconds, sleep-first, and whostate are only evaluated once, all additional consing comes from the evaluation of body and if body itself does not cons, there is no additional consing.

If sleep-first is true, the executing thread/process will sleep before the first executaion of body. If sleep-first is nil (the default), the thread will execute body immediately and then sleep.

The whostate of the thread/process will be changed to whostate while the thread/process is sleeping (while executing body, the whostate of the thread/process will be its original whostate -- see process-whostate).

This macro does not return of its own accord, but the execution of body is wrapped in a block named nil, so (return) will jump out of the loop (returning nil) and (return <form>) will jump out of the loop returning the value of <form> (see return).

Example

;; The following example shows how this macro reduces
;; consing (run in Allegro CL 10.1 SMP on a Linux platform):

(defun ltest1 ()
  (let ((ct 1000))
    (loop
      (sleep .1)
      (decf ct)
      (when (<= ct 0)
	(return)))))

(defun ltest2 ()
  (let ((ct 1000))
    (mp:do-periodically (.1 :sleep-first t)
      (decf ct)
      (when (<= ct 0)
	(return)))))

cl-user(12): (time (ltest1))
; cpu time (non-gc) 0.054992 sec user, 0.052992 sec system
; cpu time (gc)     0.001000 sec user, 0.000000 sec system
; cpu time (total)  0.055992 sec user, 0.052992 sec system
; cpu time (thread) 0.037994 sec user, 0.022997 sec system
; real time  100.182389 sec (00:01:40.182389) (.1088%)
; space allocation:
;  2,000 cons cells, 577,136 other bytes, 0 static bytes
; Page Faults: major: 0 (gc: 3), minor: 3 (gc: 3)
nil
cl-user(13): (time (ltest2))
; cpu time (non-gc) 0.045993 sec user, 0.046993 sec system
; cpu time (gc)     0.000000 sec user, 0.000000 sec system
; cpu time (total)  0.045993 sec user, 0.046993 sec system
; cpu time (thread) 0.020997 sec user, 0.025996 sec system
; real time  100.171188 sec (00:01:40.171188) (.0928%)
; space allocation:
;  2 cons cells, 368 other bytes, 0 static bytes
; Page Faults: major: 0 (gc: 0), minor: 0 (gc: 0)
nil

;; The times are roughly the same but cons cells and other bytes
;; are significantly reduced with DO-PERIODICALLY.

See multiprocessing.htm for general information on multiprocessing in Allegro CL.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 9.0 page.
Created 2015.5.21.