The moira Reference Manual

Table of Contents

The moira Reference Manual

This is the moira Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Oct 13 11:53:40 2021 GMT+0.

1 Introduction

Μοῖρα

Moira is a simple (but not quite trivial) library for monitoring and, if necessary, restarting long-running threads. In principle, it is like an in-Lisp process supervisor.

To start the monitor, you call start-monitor:

(moira:start-monitor)

Once the monitor is started, you can spawn new threads:

(moira:spawn "Background worker"
  ...))

Which is syntactic sugar for

(moira:spawn-thread
 (lambda () ...)
 :name "Background worker")

If the thread created by spawn-thread should crash, or otherwise exit abnormally, Moira will step in and restart the thread.

You can stop monitoring with stop-monitor

(moira:stop-monitor)

Although this will not affect the spawned threads.

On Linux only, Moira also tracks the thread ID (value of gettid) of the Lisp threads it launches. This can be useful for tracking the resource usage of individual thr

2 Systems

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

2.1 moira

Author

Paul M. Rodriguez <pmr@ruricolist.com>

License

MIT

Description

Monitor and restart background threads.

Dependencies

• alexandria
• serapeum
• trivial-features
• bordeaux-threads
• trivial-garbage
• osicat

Source

moira.asd (file)

Components

• package.lisp (file)
• types.lisp (file)
• thread-ids.lisp (file)
• moira.lisp (file)
• monitor.lisp (file)
• spawn.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 moira.asd

Location

moira.asd

Systems

moira (system)

3.1.2 moira/package.lisp

Parent

moira (system)

Location

package.lisp

Packages

moira

3.1.3 moira/types.lisp

Dependency

package.lisp (file)

Parent

moira (system)

Location

types.lisp

Internal Definitions

• a-thread (type)
• dead-thread (type)
• live-thread (type)
• no-thread (type)
• thread (type)
• thread-alive-p (function)

3.1.4 moira/thread-ids.lisp

Dependency

package.lisp (file)

Parent

moira (system)

Location

thread-ids.lisp

Exported Definitions

• save-current-thread-id (function)
• thread-id (function)

Internal Definitions

• *thread-ids* (special variable)
• id-thread (function)

3.1.5 moira/moira.lisp

Dependencies

• package.lisp (file)
• types.lisp (file)

Parent

moira (system)

Location

moira.lisp

Exported Definitions

list-monitored-threads (function)

Internal Definitions

• *monitored-threads* (special variable)
• clear-monitored-threads (function)
• ensure-alive (method)
• monitored-thread (class)
• monitored-thread.donep (method)
• monitored-thread.name (method)
• monitored-thread.thread (method)
• monitored-thread.thunk (method)
• start (method)
• stop (method)

3.1.6 moira/monitor.lisp

Dependencies

• package.lisp (file)
• types.lisp (file)

Parent

moira (system)

Location

monitor.lisp

Exported Definitions

• start-monitor (function)
• stop-monitor (function)

Internal Definitions

• *monitor* (special variable)
• monitor-flag (symbol macro)
• monitor-loop (function)

3.1.7 moira/spawn.lisp

Dependencies

• package.lisp (file)
• thread-ids.lisp (file)
• moira.lisp (file)

Parent

moira (system)

Location

spawn.lisp

Exported Definitions

• make-thread-saving-id (function)
• spawn (macro)
• spawn-thread (function)

Internal Definitions

make-thread-and-wait (function)

4 Packages

Packages are listed by definition order.

4.1 moira

Source

package.lisp (file)

Use List

• serapeum
• alexandria
• common-lisp

Exported Definitions

• list-monitored-threads (function)
• make-thread-saving-id (function)
• save-current-thread-id (function)
• spawn (macro)
• spawn-thread (function)
• start-monitor (function)
• stop-monitor (function)
• thread-id (function)

Internal Definitions

• *monitor* (special variable)
• *monitored-threads* (special variable)
• *thread-ids* (special variable)
• a-thread (type)
• clear-monitored-threads (function)
• dead-thread (type)
• ensure-alive (generic function)
• ensure-alive (method)
• id-thread (function)
• live-thread (type)
• make-thread-and-wait (function)
• monitor-flag (symbol macro)
• monitor-loop (function)
• monitored-thread (class)
• monitored-thread.donep (generic function)
• monitored-thread.donep (method)
• monitored-thread.name (generic function)
• monitored-thread.name (method)
• monitored-thread.thread (generic function)
• monitored-thread.thread (method)
• monitored-thread.thunk (generic function)
• monitored-thread.thunk (method)
• no-thread (type)
• start (generic function)
• start (method)
• stop (generic function)
• stop (method)
• thread (type)
• thread-alive-p (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Macros

Macro: spawn &body BODY

Like (spawn-thread (lambda () ...)).
If the first form in BODY is a string, that string is used as the name of the thread.

Package

moira

Source

spawn.lisp (file)

5.1.2 Functions

Function: list-monitored-threads ()

Package

moira

Source

moira.lisp (file)

Function: make-thread-saving-id THUNK &rest ARGS

Like ‘bt:make-thread’, but save the id of the resulting thread so it can be retrieved later with ‘moira:thread-id’.

Using ‘moira:make-thread-saving-id’ lets you start a thread that is not monitored, but does have its ID tracked.

Package

moira

Source

spawn.lisp (file)

Function: save-current-thread-id ()

Package

moira

Source

thread-ids.lisp (file)

Function: spawn-thread THUNK &key NAME

Run THUNK as a thread, automatically respawning if the thread exits abnormally.

Package

moira

Source

spawn.lisp (file)

Function: start-monitor ()

Package

moira

Source

monitor.lisp (file)

Function: stop-monitor ()

Package

moira

Source

monitor.lisp (file)

Function: thread-id THREAD

Package

moira

Source

thread-ids.lisp (file)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *monitor*

Package

moira

Source

monitor.lisp (file)

Special Variable: *monitored-threads*

Package

moira

Source

moira.lisp (file)

Special Variable: *thread-ids*

Package

moira

Source

thread-ids.lisp (file)

5.2.2 Symbol macros

Symbol Macro: monitor-flag

Package

moira

Source

monitor.lisp (file)

Expansion

moira::*storage-for-deflex-var-monitor-flag*

5.2.3 Functions

Function: clear-monitored-threads ()

Package

moira

Source

moira.lisp (file)

Function: id-thread ID

Package

moira

Source

thread-ids.lisp (file)

Function: make-thread-and-wait THUNK &rest ARGS

Like ‘make-thread-saving-id’, but wait to return until the thread is actually running.

Package

moira

Source

spawn.lisp (file)

Function: monitor-loop ()

Package

moira

Source

monitor.lisp (file)

Function: thread-alive-p X

Package

moira

Source

types.lisp (file)

5.2.4 Generic functions

Generic Function: ensure-alive SELF

Package

moira

Methods

Method: ensure-alive (SELF monitored-thread)

Source

moira.lisp (file)

Generic Function: monitored-thread.donep OBJECT

Package

moira

Methods

Method: monitored-thread.donep (MONITORED-THREAD monitored-thread)

automatically generated reader method

Source

moira.lisp (file)

Generic Function: monitored-thread.name OBJECT

Package

moira

Methods

Method: monitored-thread.name (MONITORED-THREAD monitored-thread)

automatically generated reader method

Source

moira.lisp (file)

Generic Function: monitored-thread.thread OBJECT

Package

moira

Methods

Method: monitored-thread.thread (MONITORED-THREAD monitored-thread)

automatically generated reader method

Source

moira.lisp (file)

Generic Function: monitored-thread.thunk OBJECT

Package

moira

Methods

Method: monitored-thread.thunk (MONITORED-THREAD monitored-thread)

automatically generated reader method

Source

moira.lisp (file)

Generic Function: start SELF

Package

moira

Methods

Method: start (SELF monitored-thread)

Source

moira.lisp (file)

Generic Function: stop SELF

Package

moira

Methods

Method: stop (SELF monitored-thread)

Source

moira.lisp (file)

5.2.5 Classes

Class: monitored-thread ()

Package

moira

Source

moira.lisp (file)

Direct superclasses

synchronized (class)

Direct methods

• ensure-alive (method)
• stop (method)
• start (method)
• initialize-instance (method)
• print-object (method)
• monitored-thread.name (method)
• monitored-thread.thunk (method)
• monitored-thread.donep (method)
• monitored-thread.thread (method)

Direct slots

Slot: thread

Type

moira::a-thread

Readers

monitored-thread.thread (generic function)

Slot: done

Type

boolean

Readers

monitored-thread.donep (generic function)

Slot: thunk

Type

function

Initargs

:thunk

Readers

monitored-thread.thunk (generic function)

Slot: name

Type

string

Initargs

:name

Readers

monitored-thread.name (generic function)

5.2.6 Types

Type: a-thread ()

Package

moira

Source

types.lisp (file)

Type: dead-thread ()

Package

moira

Source

types.lisp (file)

Type: live-thread ()

Package

moira

Source

types.lisp (file)

Type: no-thread ()

Package

moira

Source

types.lisp (file)

Type: thread ()

Package

moira

Source

types.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types