GBBopen 1.5 Reference -- schedule-function-relative

schedule-function-relative

schedule-function-relative name-or-scheduled-function seconds &key context marker repeat-interval verbose [Function]

Purpose
Schedule a scheduled function a specified number of seconds from now.

Package :portable-threads

Module :portable-threads

Arguments and values

name-or-scheduled-function		An object (typically a string or a symbol) naming a currently scheduled scheduled function or a `scheduled-function` object
seconds		A positive integer
context		An object (default is `nil`)
marker		An object (default is `nil`)
repeat-interval		A positive integer (representing seconds) or `nil` (default is `nil`)
verbose		A generalized boolean (default is *schedule-function-verbose*)

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 an invocation time of interval seconds from the current 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 an invocation time of interval seconds from the current time and optional repeat-interval, if specified.

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

Examples
Schedule a scheduled function that simply prints "Hello!" 5 seconds from now:

  > (schedule-function-relative
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (declare (ignore scheduled-function))
            (print "Hello!")))
       5)
  >

Schedule a scheduled function that signals a GBBopen timer-interrupt-event every 30 seconds:

  > (schedule-function-relative
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (declare (ignore scheduled-function))
            (signal-event 'timer-interrupt-event)))
      30
      :repeat-interval 30)
  >

Schedule a scheduled function that prints an individualized "Hello" message to Bob five seconds from now, repeating annoyingly every hour thereafter:

  > (schedule-function-relative
      (make-scheduled-function
        #'(lambda (scheduled-function)
            (format t "~&Hello ~a~%" 
              (scheduled-function-context scheduled-function)))
        :name 'hello
        :context "Bob")
      5
      :repeat-interval 3600)
  >

Verbosely change Bob's annoying repeating "Hello" message to greet Lisa only once, 10 seconds from now:

  > (schedule-function-relative 'hello 10
      :context "Lisa"
      :verbose 't)
  ;; Unscheduling #<scheduled-function hello [09:46:11]>...
  ;; Scheduling #<scheduled-function hello [09:46:27]>...
  >

Note
The form (schedule-function-relative scheduled-function 10) is equivalent to (schedule-function scheduled-function (+ (get-universal-time) 10)).

The GBBopen Project

schedule-function-relative