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 4.0 beta 2 "William Riker" on Mon Aug 15 05:45:06 2022 GMT+0.

Table of Contents


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>

2 Systems

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


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

2.1 rate-monotonic

A periodic thread scheduler inspired by RTEMS.

Author

Nick Patrick <npatrick04@gmail.com>

License

GPL-v3

Dependencies
  • bordeaux-threads (system).
  • timer-wheel (system).
Source

rate-monotonic.asd.

Child Component

src (module).


3 Modules

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


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

3.1 rate-monotonic/src

Source

rate-monotonic.asd.

Parent Component

rate-monotonic (system).

Child Components

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


4.1.1 rate-monotonic/rate-monotonic.asd

Source

rate-monotonic.asd.

Parent Component

rate-monotonic (system).

ASDF Systems

rate-monotonic.


4.1.2 rate-monotonic/src/package.lisp

Source

rate-monotonic.asd.

Parent Component

src (module).

Packages

rate-monotonic.


4.1.3 rate-monotonic/src/statistics.lisp

Source

rate-monotonic.asd.

Parent Component

src (module).

Public Interface
Internals

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

Source

rate-monotonic.asd.

Parent Component

src (module).

Public Interface
Internals

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

Source

rate-monotonic.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


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

5.1 rate-monotonic

Source

package.lisp.

Nickname

rm

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


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

6.1 Public Interface


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

rate-monotonic.

Source

timer-period.lisp.


6.1.2 Ordinary functions

Function: make-timer-period ()

A helper function to make a timer period object.

Package

rate-monotonic.

Source

timer-period.lisp.

Function: reset-statistics (stat)

Reset the values in a STAT struct.

Package

rate-monotonic.

Source

statistics.lisp.

Reader: stat-count (instance)
Writer: (setf stat-count) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

count.

Reader: stat-last-start (instance)
Writer: (setf stat-last-start) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

last-start.

Reader: stat-max-runtime (instance)
Writer: (setf stat-max-runtime) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

max-runtime.

Reader: stat-min-runtime (instance)
Writer: (setf stat-min-runtime) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

min-runtime.

Reader: stat-missed-count (instance)
Writer: (setf stat-missed-count) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

missed-count.

Reader: stat-total-runtime (instance)
Writer: (setf stat-total-runtime) (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Target Slot

total-runtime.

Function: timer-period-init (&optional resolution-ms wheel-size)

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

Package

rate-monotonic.

Source

timer-period.lisp.

Function: timer-period-stop ()

Shut down the underlying *TIMER-WHEEL*.

Package

rate-monotonic.

Source

timer-period.lisp.


6.1.3 Generic functions

Generic Function: cancel (period)

Cancel a period, putting it into the inactive state.

Package

rate-monotonic.

Source

rate-monotonic.lisp.

Methods
Method: cancel ((p timer-period))
Source

timer-period.lisp.

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

rate-monotonic.

Source

rate-monotonic.lisp.

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

timer-period.lisp.

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

rate-monotonic.

Source

rate-monotonic.lisp.

Methods
Method: period ((p timer-period) (type (eql :ms)) interval)
Source

timer-period.lisp.

Method: period ((p timer-period) (type (eql :seconds)) interval)
Source

timer-period.lisp.

Method: period ((p timer-period) (type (eql :ticks)) interval)
Source

timer-period.lisp.

Generic Reader: period-statistics (object)
Package

rate-monotonic.

Methods
Reader Method: period-statistics ((period period))

automatically generated reader method

Source

rate-monotonic.lisp.

Target Slot

statistics.

Generic Writer: (setf period-statistics) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf period-statistics) ((period period))

automatically generated writer method

Source

rate-monotonic.lisp.

Target Slot

statistics.

Generic Function: status (period)

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

Package

rate-monotonic.

Source

rate-monotonic.lisp.

Methods
Method: status ((p timer-period))
Source

timer-period.lisp.


6.1.4 Standalone methods

Method: print-object ((stat stat) stream)
Source

statistics.lisp.


6.1.5 Classes

Class: period
Package

rate-monotonic.

Source

rate-monotonic.lisp.

Direct subclasses

timer-period.

Direct methods
Direct slots
Slot: name
Initform

""

Initargs

:name

Readers

period-name.

Writers

(setf period-name).

Slot: state
Type

(quote rate-monotonic:state)

Initform

:inactive

Readers

period-state.

Writers

(setf period-state).

Slot: statistics
Initform

(rate-monotonic::make-stat)

Readers

period-statistics.

Writers

(setf period-statistics).

Slot: interval
Initargs

:interval

Readers

period-interval.

Writers

(setf period-interval).


Previous: , Up: Public Interface   [Contents][Index]

6.1.6 Types

Type: state ()
Package

rate-monotonic.

Source

rate-monotonic.lisp.


6.2 Internals


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

6.2.1 Special variables

Special Variable: *timer-wheel*
Package

rate-monotonic.

Source

timer-period.lisp.


6.2.2 Ordinary functions

Function: copy-stat (instance)
Package

rate-monotonic.

Source

statistics.lisp.

Function: make-stat (&key count missed-count max-runtime total-runtime min-runtime last-start)
Package

rate-monotonic.

Source

statistics.lisp.

Function: make-timer-period-timeout (timer-period)

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

Package

rate-monotonic.

Source

timer-period.lisp.

Function: stat-p (object)
Package

rate-monotonic.

Source

statistics.lisp.

Function: update-statistics (stat this-time)

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

Package

rate-monotonic.

Source

statistics.lisp.


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

6.2.3 Generic functions

Generic Reader: period-interval (object)
Package

rate-monotonic.

Methods
Reader Method: period-interval ((period period))

automatically generated reader method

Source

rate-monotonic.lisp.

Target Slot

interval.

Generic Writer: (setf period-interval) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf period-interval) ((period period))

automatically generated writer method

Source

rate-monotonic.lisp.

Target Slot

interval.

Generic Reader: period-name (object)
Package

rate-monotonic.

Methods
Reader Method: period-name ((period period))

automatically generated reader method

Source

rate-monotonic.lisp.

Target Slot

name.

Generic Writer: (setf period-name) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf period-name) ((period period))

automatically generated writer method

Source

rate-monotonic.lisp.

Target Slot

name.

Generic Reader: period-state (object)
Package

rate-monotonic.

Methods
Reader Method: period-state ((period period))

automatically generated reader method

Source

rate-monotonic.lisp.

Target Slot

state.

Generic Writer: (setf period-state) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf period-state) ((period period))

automatically generated writer method

Source

rate-monotonic.lisp.

Target Slot

state.

Generic Reader: timer-cv (object)
Package

rate-monotonic.

Methods
Reader Method: timer-cv ((timer-period timer-period))

automatically generated reader method

Source

timer-period.lisp.

Target Slot

cv.

Generic Writer: (setf timer-cv) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf timer-cv) ((timer-period timer-period))

automatically generated writer method

Source

timer-period.lisp.

Target Slot

cv.

Generic Reader: timer-lock (object)
Package

rate-monotonic.

Methods
Reader Method: timer-lock ((timer-period timer-period))

automatically generated reader method

Source

timer-period.lisp.

Target Slot

lock.

Generic Writer: (setf timer-lock) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf timer-lock) ((timer-period timer-period))

automatically generated writer method

Source

timer-period.lisp.

Target Slot

lock.

Generic Reader: timer-period-timer (object)
Package

rate-monotonic.

Methods
Reader Method: timer-period-timer ((timer-period timer-period))

automatically generated reader method

Source

timer-period.lisp.

Target Slot

timer.

Generic Writer: (setf timer-period-timer) (object)
Package

rate-monotonic.

Methods
Writer Method: (setf timer-period-timer) ((timer-period timer-period))

automatically generated writer method

Source

timer-period.lisp.

Target Slot

timer.


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

6.2.4 Structures

Structure: stat
Package

rate-monotonic.

Source

statistics.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: count
Package

common-lisp.

Initform

0

Readers

stat-count.

Writers

(setf stat-count).

Slot: missed-count
Initform

0

Readers

stat-missed-count.

Writers

(setf stat-missed-count).

Slot: max-runtime
Initform

0

Readers

stat-max-runtime.

Writers

(setf stat-max-runtime).

Slot: total-runtime
Initform

0

Readers

stat-total-runtime.

Writers

(setf stat-total-runtime).

Slot: min-runtime
Initform

0

Readers

stat-min-runtime.

Writers

(setf stat-min-runtime).

Slot: last-start
Initform

0

Readers

stat-last-start.

Writers

(setf stat-last-start).


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

6.2.5 Classes

Class: timer-period
Package

rate-monotonic.

Source

timer-period.lisp.

Direct superclasses

period.

Direct methods
Direct slots
Slot: timer
Initargs

:timer

Readers

timer-period-timer.

Writers

(setf timer-period-timer).

Slot: lock
Initform

(bordeaux-threads:make-lock)

Readers

timer-lock.

Writers

(setf timer-lock).

Slot: cv
Initform

(bordeaux-threads:make-condition-variable)

Readers

timer-cv.

Writers

(setf timer-cv).


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  
Index Entry  Section

(
(setf period-interval): Private generic functions
(setf period-interval): Private generic functions
(setf period-name): Private generic functions
(setf period-name): Private generic functions
(setf period-state): Private generic functions
(setf period-state): Private generic functions
(setf period-statistics): Public generic functions
(setf period-statistics): Public generic functions
(setf stat-count): Public ordinary functions
(setf stat-last-start): Public ordinary functions
(setf stat-max-runtime): Public ordinary functions
(setf stat-min-runtime): Public ordinary functions
(setf stat-missed-count): Public ordinary functions
(setf stat-total-runtime): Public ordinary functions
(setf timer-cv): Private generic functions
(setf timer-cv): Private generic functions
(setf timer-lock): Private generic functions
(setf timer-lock): Private generic functions
(setf timer-period-timer): Private generic functions
(setf timer-period-timer): Private generic functions

C
cancel: Public generic functions
cancel: Public generic functions
copy-stat: Private ordinary functions

F
finish-period: Public generic functions
finish-period: Public generic functions
Function, (setf stat-count): Public ordinary functions
Function, (setf stat-last-start): Public ordinary functions
Function, (setf stat-max-runtime): Public ordinary functions
Function, (setf stat-min-runtime): Public ordinary functions
Function, (setf stat-missed-count): Public ordinary functions
Function, (setf stat-total-runtime): Public ordinary functions
Function, copy-stat: Private ordinary functions
Function, make-stat: Private ordinary functions
Function, make-timer-period: Public ordinary functions
Function, make-timer-period-timeout: Private ordinary functions
Function, reset-statistics: Public ordinary functions
Function, stat-count: Public ordinary functions
Function, stat-last-start: Public ordinary functions
Function, stat-max-runtime: Public ordinary functions
Function, stat-min-runtime: Public ordinary functions
Function, stat-missed-count: Public ordinary functions
Function, stat-p: Private ordinary functions
Function, stat-total-runtime: Public ordinary functions
Function, timer-period-init: Public ordinary functions
Function, timer-period-stop: Public ordinary functions
Function, update-statistics: Private ordinary functions

G
Generic Function, (setf period-interval): Private generic functions
Generic Function, (setf period-name): Private generic functions
Generic Function, (setf period-state): Private generic functions
Generic Function, (setf period-statistics): Public generic functions
Generic Function, (setf timer-cv): Private generic functions
Generic Function, (setf timer-lock): Private generic functions
Generic Function, (setf timer-period-timer): Private generic functions
Generic Function, cancel: Public generic functions
Generic Function, finish-period: Public generic functions
Generic Function, period: Public generic functions
Generic Function, period-interval: Private generic functions
Generic Function, period-name: Private generic functions
Generic Function, period-state: Private generic functions
Generic Function, period-statistics: Public generic functions
Generic Function, status: Public generic functions
Generic Function, timer-cv: Private generic functions
Generic Function, timer-lock: Private generic functions
Generic Function, timer-period-timer: Private generic functions

M
Macro, with-timer-period: Public macros
make-stat: Private ordinary functions
make-timer-period: Public ordinary functions
make-timer-period-timeout: Private ordinary functions
Method, (setf period-interval): Private generic functions
Method, (setf period-name): Private generic functions
Method, (setf period-state): Private generic functions
Method, (setf period-statistics): Public generic functions
Method, (setf timer-cv): Private generic functions
Method, (setf timer-lock): Private generic functions
Method, (setf timer-period-timer): Private generic functions
Method, cancel: Public generic functions
Method, finish-period: Public generic functions
Method, period: Public generic functions
Method, period: Public generic functions
Method, period: Public generic functions
Method, period-interval: Private generic functions
Method, period-name: Private generic functions
Method, period-state: Private generic functions
Method, period-statistics: Public generic functions
Method, print-object: Public standalone methods
Method, status: Public generic functions
Method, timer-cv: Private generic functions
Method, timer-lock: Private generic functions
Method, timer-period-timer: Private generic functions

P
period: Public generic functions
period: Public generic functions
period: Public generic functions
period: Public generic functions
period-interval: Private generic functions
period-interval: Private generic functions
period-name: Private generic functions
period-name: Private generic functions
period-state: Private generic functions
period-state: Private generic functions
period-statistics: Public generic functions
period-statistics: Public generic functions
print-object: Public standalone methods

R
reset-statistics: Public ordinary functions

S
stat-count: Public ordinary functions
stat-last-start: Public ordinary functions
stat-max-runtime: Public ordinary functions
stat-min-runtime: Public ordinary functions
stat-missed-count: Public ordinary functions
stat-p: Private ordinary functions
stat-total-runtime: Public ordinary functions
status: Public generic functions
status: Public generic functions

T
timer-cv: Private generic functions
timer-cv: Private generic functions
timer-lock: Private generic functions
timer-lock: Private generic functions
timer-period-init: Public ordinary functions
timer-period-stop: Public ordinary functions
timer-period-timer: Private generic functions
timer-period-timer: Private generic functions

U
update-statistics: Private ordinary functions

W
with-timer-period: Public macros

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