Common Lisp Package: COM.INFORMATIMAGO.COMMON-LISP.CESARUM.ACTIVITY

This package implements a kind of co-routine monitor. An activity is a closure that is called at specified times (T+k*P). It should return before processing can go on. This package is implemented in pure Common Lisp and allows to schedule independent "tasks" portably, as long as you can split each task in small chunks, timewise. License: AGPL3 Copyright Pascal J. Bourguignon 2003 - 2012 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

README:

FUNCTION

Public

ACTIVITY-RUN (&KEY ONE-STEP UNTIL)

DO: Runs the scheduler. ONE-STEP: If true, runs only one activity (or don't sleep). UNTIL: Time (in universal-time seconds) until which activities must be run.

ACTIVITY-YIELD

DO: Returns control to the scheduler. NOTE: This may be called from an activity closure to return early to the scheduler.

ACTIVITYP (OBJECT)

RETURN: Whether the OBJECT is an instance of the ACTIVITY class (or one of its subclasses).

ALL-ACTIVITIES

RETURN: A new list of all the activities.

CURRENT-ACTIVITY

RETURN: The current activity.

DESTROY-ACTIVITY (ACTIVITY)

DO: Remove the activity from the scheduling queue.

MAKE-ACTIVITY (FUNCTION &KEY (NAME Unnamed activity) (START-AT 0 START-AT-P) (START-IN 0 START-IN-P) (PERIOD 1) (DROPABLE NIL) (EXACT NIL) (IDLE NIL) ((SCHEDULER *SCHEDULER*) *SCHEDULER*))

FUNCTION: A closure, that will be repeatitively called at specified times. NAME: A string, naming the activity. PERIOD: A real indicating the period of the activity. If 0 then run it when idle. START-AT: (mutually exclusive with START-IN) The first universal-time at which the activity should run. START-IN: (mutually exclusive with START-AT) The number of seconds from now when the activity should be run first. If none of START-AT or START-IN is specified, the start time is now. *SCHEDULER* The scheduler used to run this activity.

Private

GET-REAL-TIME

RETURN: The universal-time (in seconds), offset by the internal-real-time fraction.

SCHEDULE (CURRENT-TIME SCHEDULED-TIME PERIOD DROPABLEP EXACTP IDLEP PRECISION)

RETURN: (values runp next-scheduled-time) NOTE: exactp => dropablep idlep <=> (zerop period)

Undocumented

ACT-CREATED-MENU

CDEBUGGER (&OPTIONAL (REASON User request))

FORMAT-FOR-FIELD (ACTIVITIES FIELD WIDTH PRECISION)

FORMATALOT (CONTROL-STRING &REST ARGUMENTS)

GET-NEXT-ACTIVITY-ID

GET-RUN-TIME

MAKE-SCHEDULER (TIME-BASE)

TEST (&KEY DEBUG)

MACRO

Private

Undocumented

DEFINE-MENU (NAME TITLE &REST ITEMS)

WITH-DEBUG (DEBUG &BODY BODY)

GENERIC-FUNCTION

Public

GET-TIME (TIMEBASE)

RETURN: Current number of seconds since epoch. TIMEBASE: :universal-time to get the time from (get-univeral-time), :real-time to get the time from (get-internal-real-time), :run-time to get the time from (get-internal-run-time). (in all cases, the time is in number of seconds since the epoch).

Private

PRECISION (TIMEBASE)

Return the number of seconds (or fraction of a second) that is the minimum non-zero difference between two calls to GET-TIME.

WAIT-DELAY (TIMEBASE DELAY)

Sleep for DELAY seconds. The default is to use CL:SLEEP. A 'persistent' scheduler could, when DELAY is big, save the image, setup the system to be launched again after the DELAY is elapsed and restart the scheduling then.

Undocumented

DEBUGGER-INVOCATION-FORMAT-ARGUMENTS (CONDITION)

SETFDEBUGGER-INVOCATION-FORMAT-ARGUMENTS (NEW-VALUE CONDITION)

DEBUGGER-INVOCATION-FORMAT-CONTROL (CONDITION)

SETFDEBUGGER-INVOCATION-FORMAT-CONTROL (NEW-VALUE CONDITION)

FIND-ACTIVITY-BY-ID (SCHEDULER ACTIVITY-ID)

RUN (SCHEDULER &KEY ONE-STEP UNTIL)

SCHEDULE-ACTIVITY (SCHEDULER ACTIVITY)

SCHEDULER-ALL-ACTIVITIES (SCHEDULER)

TIME-SCHEDULER-IDLE-ACTIVITIES (SCHEDULER)

UNSCHEDULE-ACTIVITY (SCHEDULER ACTIVITY)

SLOT-ACCESSOR

Public

ACTIVITY-CLOSURE (ACTIVITY)

The RETURN: the closure executed each time the activity is scheduled.

SETFACTIVITY-CLOSURE (NEW-VALUE OBJECT)

Set the RETURN: the closure executed each time the activity is scheduled.

ACTIVITY-DROPABLE-P (ACTIVITY)

The RETURN: Whether the activity should be skipped instead of scheduled too late.

SETFACTIVITY-DROPABLE-P (NEW-VALUE OBJECT)

Set the RETURN: Whether the activity should be skipped instead of scheduled too late.

ACTIVITY-EXACT-P (ACTIVITY)

The RETURN: Whether the activity should be run only on exact time.

SETFACTIVITY-EXACT-P (NEW-VALUE OBJECT)

Set the RETURN: Whether the activity should be run only on exact time.

ACTIVITY-NAME (ACTIVITY)

The RETURN: A label for the activity.

SETFACTIVITY-NAME (NEW-VALUE OBJECT)

Set the RETURN: A label for the activity.

ACTIVITY-PERIOD (ACTIVITY)

The RETURN: The period of this activity, expressed in seconds. If zero, then the activity is run as often as possible.

SETFACTIVITY-PERIOD (NEW-VALUE OBJECT)

Set the RETURN: The period of this activity, expressed in seconds. If zero, then the activity is run as often as possible.

ACTIVITY-SCHEDULED-TIME (ACTIVITY)

The RETURN: The scheduled time this activity should run.

SETFACTIVITY-SCHEDULED-TIME (NEW-VALUE OBJECT)

Set the RETURN: The scheduled time this activity should run.

Private

ACTIVITY-ID (OBJECT)

A unique ID for activities.

ACTIVITY-SCHEDULER (OBJECT)

The scheduler that schedules this activity.

SETFACTIVITY-SCHEDULER (NEW-VALUE OBJECT)

The scheduler that schedules this activity.

IDLE-SCHEDULER-MAIN-SCHEDULER (OBJECT)

The scheduler that should be given the activities that are not idle activities anymore (ie with period>0.

SETFIDLE-SCHEDULER-MAIN-SCHEDULER (NEW-VALUE OBJECT)

The scheduler that should be given the activities that are not idle activities anymore (ie with period>0.

SCHEDULER-ACTIVITIES (OBJECT)

The list of activities scheduled by this scheduler.

SETFSCHEDULER-ACTIVITIES (NEW-VALUE OBJECT)

The list of activities scheduled by this scheduler.

SCHEDULER-TIME-BASE (OBJECT)

The time-base used by this scheduler.

SETFSCHEDULER-TIME-BASE (NEW-VALUE OBJECT)

The time-base used by this scheduler.

TIME-SCHEDULER-IDLE-SCHEDULER (OBJECT)

The scheduler used when there's nothing to run for a while.

SETFTIME-SCHEDULER-IDLE-SCHEDULER (NEW-VALUE OBJECT)

The scheduler used when there's nothing to run for a while.

VARIABLE

Private

*CURRENT-ACTIVITY*

The current activity.

*INTERNAL-TIME-UNIT*

The internal time slice, in seconds, as a DOUBLE-FLOAT.

*PRECISE-REAL-TIME-OFFSET*

Contains the number of seconds that must be added to: (/ (GET-INTERNAL-REAL-TIME) INTERNAL-TIME-UNITS-PER-SECOND) to get the current universal-time with the higher internal time precision.

*RESCHEDULED*

Ugly hack: If an idle activity creates a new periodic class, or otherwise changes the schedule, the idle-scheduler needs to yield the hand to it's time-scheduler.

Undocumented

*DEBUG*

*SCHEDULER*

CLASS

Private

ACTIVITY

An activity to be scheduled.

IDLE-SCHEDULER

The Idle Scheduler just runs the activities in round-robin fashion for

SCHEDULER

The base class for schedulers.

TIME-SCHEDULER

The time scheduler runs activities at given times.

CONDITION

Private

DEBUGGER-INVOCATION

SBCL expects for INVOKE-DEBUGGER, objects of type CL:CONDITION, not mere 'condition' objects.