# The rate-monotonic Reference Manual

Next: , Previous: , Up: (dir)   [Contents][Index]

# The rate-monotonic Reference Manual

This is the rate-monotonic Reference Manual, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:31:07 2018 GMT+0.

Next: , Previous: , Up: Top   [Contents][Index]

## 1 Introduction

Rate-monotonic is a free (GPL) Common Lisp library for scheduling periodic threads. It provides an API inspired by the RTEMS (also GPL) Rate Monotonic Manager.

# Example

The first is a simple example of a period scheduled to elapse every 500 milliseconds. The statistics are measuring time in internal-real-time units, capturing minimum, maximum, and average time it takes to exit a period call to the subsequent period call. In this case, it takes less than 1 millisecond to loop.

``````CL-USER> (rm:with-timer-period ()
(let ((p (rm:make-timer-period)))
(dotimes (i 11)
(rm:period p :ms 500)
(format t "i: ~A~%" i)
(force-output))

(rm:period-statistics p)))
i: 0
i: 1
i: 2
i: 3
i: 4
i: 5
i: 6
i: 7
i: 8
i: 9
i: 10
#<STAT :COUNT 10 :MISSED 0 :MIN 0 :AVG 0 :MAX 0>
``````

The next example adds a sleep call, and a call to STATUS which returns the period state and time since exiting PERIOD. The first sleep call starts at 10 milliseconds, increasing by 10 milliseconds each loop. Since the period is constant at 100 milliseconds, the STATUS call eventually returns :EXPIRED, and the statistics show 5 missed periods in this case.

``````CL-USER> (rm:with-timer-period (25)
(let ((p (rm:make-timer-period)))
(dotimes (i 14)
(rm:period p :seconds 0.1)
(sleep (* 0.01 (1+ i)))
(multiple-value-bind
(state time) (rm:status p)
(format t "i: ~D :state ~A :time ~A~%"
i state time))
(force-output))
(rm:period-statistics p)))
i: 0 :state RUNNING :time 10
i: 1 :state RUNNING :time 21
i: 2 :state RUNNING :time 31
i: 3 :state RUNNING :time 41
i: 4 :state RUNNING :time 50
i: 5 :state RUNNING :time 60
i: 6 :state RUNNING :time 70
i: 7 :state RUNNING :time 81
i: 8 :state RUNNING :time 90
i: 9 :state EXPIRED :time 101
i: 10 :state EXPIRED :time 112
i: 11 :state EXPIRED :time 121
i: 12 :state EXPIRED :time 131
i: 13 :state EXPIRED :time 141
#<STAT :COUNT 13 :MISSED 5 :MIN 10 :AVG 72 :MAX 131>
``````

Next: , Previous: , Up: Top   [Contents][Index]

## 2 Systems

The main system appears first, followed by any subsystem dependency.

Previous: , Up: Systems   [Contents][Index]

### 2.1 rate-monotonic

Author

Nick Patrick <npatrick04@gmail.com>

GPL-v3

Description

A periodic thread scheduler inspired by RTEMS.

Dependencies
• timer-wheel
Source

rate-monotonic.asd (file)

Component

src (module)

Next: , Previous: , Up: Top   [Contents][Index]

## 3 Modules

Modules are listed depth-first from the system components tree.

Previous: , Up: Modules   [Contents][Index]

### 3.1 rate-monotonic/src

Parent

rate-monotonic (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

## 4 Files

Files are sorted by type and then listed depth-first from the systems components trees.

Previous: , Up: Files   [Contents][Index]

### 4.1 Lisp

Next: , Previous: , Up: Lisp files   [Contents][Index]

#### 4.1.1 rate-monotonic.asd

Location

rate-monotonic.asd

Systems

rate-monotonic (system)

Parent

src (module)

Location

src/package.lisp

Packages

#### 4.1.3 rate-monotonic/src/statistics.lisp

Parent

src (module)

Location

src/statistics.lisp

Exported Definitions
Internal Definitions

#### 4.1.4 rate-monotonic/src/rate-monotonic.lisp

Parent

src (module)

Location

src/rate-monotonic.lisp

Exported Definitions
Internal Definitions

#### 4.1.5 rate-monotonic/src/timer-period.lisp

Parent

src (module)

Location

src/timer-period.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 5 Packages

Packages are listed by definition order.

Previous: , Up: Packages   [Contents][Index]

### 5.1 rate-monotonic

Source

package.lisp (file)

Nickname

rm

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

## 6 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

Next: , Previous: , Up: Definitions   [Contents][Index]

### 6.1 Exported definitions

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 6.1.1 Macros

Macro: with-timer-period (&optional RESOLUTION-MS WHEEL-SIZE) &body BODY

Execute BODY with the *TIMER-WHEEL* initialized and running.

Package
Source

timer-period.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 6.1.2 Functions

Function: make-timer-period ()

A helper function to make a timer period object.

Package
Source

timer-period.lisp (file)

Function: reset-statistics STAT

Reset the values in a STAT struct.

Package
Source

statistics.lisp (file)

Function: stat-count INSTANCE
Function: (setf stat-count) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: stat-last-start INSTANCE
Function: (setf stat-last-start) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: stat-max-runtime INSTANCE
Function: (setf stat-max-runtime) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: stat-min-runtime INSTANCE
Function: (setf stat-min-runtime) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: stat-missed-count INSTANCE
Function: (setf stat-missed-count) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: stat-total-runtime INSTANCE
Function: (setf stat-total-runtime) VALUE INSTANCE
Package
Source

statistics.lisp (file)

Function: timer-period-init &optional RESOLUTION-MS WHEEL-SIZE

Initialize the underlying *TIMER-WHEEL* with provided RESOLUTION-MS and WHEEL-SIZE.

Package
Source

timer-period.lisp (file)

Function: timer-period-stop ()

Shut down the underlying *TIMER-WHEEL*.

Package
Source

timer-period.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 6.1.3 Generic functions

Generic Function: cancel PERIOD

Cancel a period, putting it into the inactive state.

Package
Source

rate-monotonic.lisp (file)

Methods
Method: cancel (P timer-period)
Source

timer-period.lisp (file)

Generic Function: finish-period PERIOD

Complete a running PERIOD without restarting it. The period
will not block on this call. The return value is :SUCCESSFUL when calling prior to the previous interval.

If a running period interval has already elapsed, the call returns :TIMEOUT.

This does essentially the same thing as CANCEL, but this captures statistics.

Package
Source

rate-monotonic.lisp (file)

Methods
Method: finish-period (P timer-period)
Source

timer-period.lisp (file)

Generic Function: period PERIOD TYPE INTERVAL

Initiate a PERIOD with the provided INTERVAL. If a PERIOD is
already running, then the thread will block for the remainder of the interval at which point the thread is unblocked for the new duration. The return value is :SUCCESSFUL when initiating or calling prior to the previous interval.

If a running period interval has already elapsed, the period is re-initiated with the new interval, and the call returns :TIMEOUT.

TYPE can be one of the following:
- :TICKS - INTERVAL is an unsigned integer indicating an interval in the underlying resolution.
- :SECONDS - INTERVAL is a real value.
- :MS - INTERVAL is an integral millisecond interval.

Package
Source

rate-monotonic.lisp (file)

Methods
Method: period (P timer-period) (TYPE (eql ms)) INTERVAL
Source

timer-period.lisp (file)

Method: period (P timer-period) (TYPE (eql seconds)) INTERVAL
Source

timer-period.lisp (file)

Method: period (P timer-period) (TYPE (eql ticks)) INTERVAL
Source

timer-period.lisp (file)

Generic Function: period-statistics OBJECT
Generic Function: (setf period-statistics) NEW-VALUE OBJECT
Package
Methods
Method: period-statistics (PERIOD period)

Source

rate-monotonic.lisp (file)

Method: (setf period-statistics) NEW-VALUE (PERIOD period)

automatically generated writer method

Source

rate-monotonic.lisp (file)

Generic Function: status PERIOD

Return the status of the period in 2 values.
- State - :EXPIRED, :READY, :INACTIVE, or :RUNNING - Time since last period.

Package
Source

rate-monotonic.lisp (file)

Methods
Method: status (P timer-period)
Source

timer-period.lisp (file)

Next: , Previous: , Up: Exported definitions   [Contents][Index]

#### 6.1.4 Classes

Class: period ()
Package
Source

rate-monotonic.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses

timer-period (class)

Direct methods
Direct slots
Slot: name
Initargs

:name

Initform

""

period-name (generic function)

Writers

(setf period-name) (generic function)

Slot: state
Type

(quote rate-monotonic:state)

Initform

:inactive

period-state (generic function)

Writers

(setf period-state) (generic function)

Slot: statistics
Initform

(rate-monotonic::make-stat)

period-statistics (generic function)

Writers

(setf period-statistics) (generic function)

Slot: interval
Initargs

:interval

period-interval (generic function)

Writers

(setf period-interval) (generic function)

Previous: , Up: Exported definitions   [Contents][Index]

#### 6.1.5 Types

Type: state ()
Package
Source

rate-monotonic.lisp (file)

Previous: , Up: Definitions   [Contents][Index]

### 6.2 Internal definitions

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 6.2.1 Special variables

Special Variable: *timer-wheel*
Package
Source

timer-period.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 6.2.2 Functions

Function: copy-stat INSTANCE
Package
Source

statistics.lisp (file)

Function: make-stat &key (COUNT COUNT) (MISSED-COUNT MISSED-COUNT) (MAX-RUNTIME MAX-RUNTIME) (TOTAL-RUNTIME TOTAL-RUNTIME) (MIN-RUNTIME MIN-RUNTIME) (LAST-START LAST-START)
Package
Source

statistics.lisp (file)

Function: make-timer-period-timeout TIMER-PERIOD

An internal function that returns a timeout lambda for the given TIMER-PERIOD.

Package
Source

timer-period.lisp (file)

Function: stat-p OBJECT
Package
Source

statistics.lisp (file)

Function: update-statistics STAT THIS-TIME

Update STAT object with internal-real-time deltat THIS-TIME for a period.

Package
Source

statistics.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 6.2.3 Generic functions

Generic Function: period-interval OBJECT
Generic Function: (setf period-interval) NEW-VALUE OBJECT
Package
Methods
Method: period-interval (PERIOD period)

Source

rate-monotonic.lisp (file)

Method: (setf period-interval) NEW-VALUE (PERIOD period)

automatically generated writer method

Source

rate-monotonic.lisp (file)

Generic Function: period-name OBJECT
Generic Function: (setf period-name) NEW-VALUE OBJECT
Package
Methods
Method: period-name (PERIOD period)

Source

rate-monotonic.lisp (file)

Method: (setf period-name) NEW-VALUE (PERIOD period)

automatically generated writer method

Source

rate-monotonic.lisp (file)

Generic Function: period-state OBJECT
Generic Function: (setf period-state) NEW-VALUE OBJECT
Package
Methods
Method: period-state (PERIOD period)

Source

rate-monotonic.lisp (file)

Method: (setf period-state) NEW-VALUE (PERIOD period)

automatically generated writer method

Source

rate-monotonic.lisp (file)

Generic Function: timer-cv OBJECT
Generic Function: (setf timer-cv) NEW-VALUE OBJECT
Package
Methods
Method: timer-cv (TIMER-PERIOD timer-period)

Source

timer-period.lisp (file)

Method: (setf timer-cv) NEW-VALUE (TIMER-PERIOD timer-period)

automatically generated writer method

Source

timer-period.lisp (file)

Generic Function: timer-lock OBJECT
Generic Function: (setf timer-lock) NEW-VALUE OBJECT
Package
Methods
Method: timer-lock (TIMER-PERIOD timer-period)

Source

timer-period.lisp (file)

Method: (setf timer-lock) NEW-VALUE (TIMER-PERIOD timer-period)

automatically generated writer method

Source

timer-period.lisp (file)

Generic Function: timer-period-timer OBJECT
Generic Function: (setf timer-period-timer) NEW-VALUE OBJECT
Package
Methods
Method: timer-period-timer (TIMER-PERIOD timer-period)

Source

timer-period.lisp (file)

Method: (setf timer-period-timer) NEW-VALUE (TIMER-PERIOD timer-period)

automatically generated writer method

Source

timer-period.lisp (file)

Next: , Previous: , Up: Internal definitions   [Contents][Index]

#### 6.2.4 Structures

Structure: stat ()
Package
Source

statistics.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots
Slot: count
Initform

0

stat-count (function)

Writers

(setf stat-count) (function)

Slot: missed-count
Initform

0

stat-missed-count (function)

Writers

(setf stat-missed-count) (function)

Slot: max-runtime
Initform

0

stat-max-runtime (function)

Writers

(setf stat-max-runtime) (function)

Slot: total-runtime
Initform

0

stat-total-runtime (function)

Writers

(setf stat-total-runtime) (function)

Slot: min-runtime
Initform

0

stat-min-runtime (function)

Writers

(setf stat-min-runtime) (function)

Slot: last-start
Initform

0

stat-last-start (function)

Writers

(setf stat-last-start) (function)

Previous: , Up: Internal definitions   [Contents][Index]

#### 6.2.5 Classes

Class: timer-period ()
Package
Source

timer-period.lisp (file)

Direct superclasses

period (class)

Direct methods
Direct slots
Slot: timer
Initargs

:timer

timer-period-timer (generic function)

Writers

(setf timer-period-timer) (generic function)

Slot: lock
Initform

timer-lock (generic function)

Writers

(setf timer-lock) (generic function)

Slot: cv
Initform

timer-cv (generic function)

Writers

(setf timer-cv) (generic function)

Previous: , Up: Top   [Contents][Index]

## Appendix A Indexes

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.1 Concepts

Next: , Previous: , Up: Indexes   [Contents][Index]

### A.2 Functions

Jump to: (   C   F   G   M   P   R   S   T   U   W
Jump to: (   C   F   G   M   P   R   S   T   U   W

Next: , Previous: , Up: Indexes   [Contents][Index]