schedule-function

Purpose
Schedule a scheduled function at an absolute invocation time.

Package   :portable-threads

Module   :portable-threads

Arguments and values

Errors
Threads (multiprocessing) is not supported on the Common Lisp implementation.

Description
If the scheduled function is unscheduled, the scheduled-function object must be specified as the name-or-scheduled-function value. In this case, the scheduled function it is added to the list of currently scheduled scheduled functions with the specified invocation-time and optional repeat-interval, if specified.

If the scheduled-function object is currently scheduled, either the scheduled-function object or the optional name value that was specified when the scheduled-function object was created with make-scheduled-function can be specified as the name-or-scheduled-function value. If a name is specified as the name-or-scheduled-function value and more than one scheduled function with the specified name is currently scheduled, the scheduled function with the earliest invocation time is selected. If an optional marker value was specified along with name when the scheduled-function object was created with make-scheduled-function, the marker value can also be specified to restrict the selected scheduled function to the one with the earliest invocation time that matches both the name and marker values. The selected scheduled function is first unscheduled and then rescheduled with the specified invocation-time and optional repeat-interval, if specified.

The optional context object can be specified to replace the invocation context in the scheduled-function object.

See also
    *schedule-function-verbose*
    all-scheduled-functions
    encode-time-of-day
    make-scheduled-function
    restart-scheduled-function-scheduler
    schedule-function-relative
    scheduled-function-repeat-interval
    scheduled-function-scheduler-paused-p
    scheduled-function-scheduler-running-p
    spawn-periodic-function
    unschedule-function

Examples
Schedule a scheduled function that simply prints "Happy New Year!" at midnight (local time) on January 1, 2014:

  > (schedule-function
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (declare (ignore scheduled-function))
            (print "Happy New Year!")))
       (encode-universal-time 0 0 0 1 1 2014))
  > (all-scheduled-functions)
  (#<scheduled-function nil [Jan 1, 2014 00:00:00]>)
  >

  > (schedule-function
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (declare (ignore scheduled-function))
            (print "It's quitting time!"))
        :name 'quitting-time)
      (encode-time-of-day 0 0 17) 
      :repeat-interval #.(* 24 60 60))
  >

  > (schedule-function 'quitting-time (encode-time-of-day 0 30 17)
      :repeat-interval #.(* 24 60 60)
      :verbose 't)
  ;; Unscheduling #<scheduled-function quitting-time [17:00:00]>...
  ;; Scheduling #<scheduled-function quitting-time [17:30:00]> 
  ;; as the next scheduled-function...
  >

Schedule a scheduled function that prints an individualized "Hello" message to Bob every day at 9am:

  > (schedule-function
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (format t "~&Hello ~a~%" 
              (scheduled-function-context scheduled-function)))
        :name 'hello
        :context "Bob")
      (encode-time-of-day 0 0 9)
      :repeat-interval #.(* 24 60 60))
  >

  > (schedule-function 'hello (encode-time-of-day 0 30 8)
      :repeat-interval #.(* 24 60 60)
      :context "Lisa"
      :verbose 't)
  ;; Unscheduling #<scheduled-function hello [09:00:00]>...
  ;; Scheduling #<scheduled-function hello [08:30:00]> 
  ;; as the next scheduled-function...
  >

schedule-function