The auto-restart Reference Manual

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

The auto-restart Reference Manual

This is the auto-restart Reference Manual, version 0.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 03:17:47 2022 GMT+0.

Table of Contents


1 Introduction

AUTO-RESTART

tdrhq

Auto-restart makes it easy to create restarts for the most common situation of just retrying a function. To summarize, this is how you'll use it:

(with-auto-restart ()
  (defun foo(arg1 &key other-options)
    (... do-stuff ...)))

If something fails inside foo, you'll be presented with a restart to RETRY-FOO. Once you've pushed this to production you might that the function FOO is flaky, possibly because it hits the network or some other unreliable resource. In that case, you can automate calling the restart like so:

(with-auto-restart (:retries 2 :sleep 1)
  (defun foo(arg1 &key other-options)
    (... do-stuff ...)))

This is really it, but you might have some questions as to why the API is as it is. Let's build up the reasoning for this.

Motivation

So say you write a complex, slow running function FOO:

(defun foo (...args ...)
  (... do-stuff ...))

It's part of a slow job, say a crawler, so if the function FOO fails, you don't want to restart the job from scratch. Instead, you probably just want to restart the FOO function. You might consider doing something like this:

(defun foo (...args...)
  (labels ((actual-foo ()
             (restart-case
                (...do-stuff...)
               (retry-foo ()
                (actual-foo)))))
     (actual-foo)

Now, when an error happens you'll get a restart to RETRY-FOO. But there's a catch! If you make changes to (...do stuff...), those changes won't show up even if you RETRY-FOO.

So we'll do something like this instead:

(defun foo (...args...)
  (restart-case
     (...do-stuff...)
    (retry-foo ()
      (foo ...args...))))

This version works great. Applying ...args... on the last line needs to be done carefully. You need to account for &optional, &key etc. Also, any changes to the args needs to be correctly kept in sync on the last line. So it's error prone.

with-auto-restart just does this for you automatically.

Retries

In the process of developing, you'll end up testing that the restart works correctly. (Restarts need to be verified too! It's just code after all! A restart might fail, if for example some global state has changed beforethe condition was signaled).

But you might find that the FOO function keeps failing for legitimate reasons. Perhaps it's hitting the network, or some other resource that's not always available. Using :retries makes it trivial to update the existing function to automatically call the retry for you multiple times.

Future work

One thing I would like to do, but I don't know if this is possible, is to be able to enter the debugger, but if no action was chosen with a set amount of time, then automatically pick a restart.

The lambda-list parsing is also very primitive. If you have some complex lambda-list keywords, we may or may not get it right. Do look at the macroexpansion to make sure it's doing the right thing. We should handle &optional, &key and &rest at a minimum.

Authors

Built by Arnold Noronha arnold@tdrhq.com

License

Licensed under the Mozilla Public License, v2.


2 Systems

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


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

2.1 auto-restart

automatically generate restart-cases for the most common use cases, and also use the restart for automatic retries

Author

Arnold Noronha <arnold@jipr.io>

License

Apache License, Version 2.0

Version

0.0.1

Dependency

iterate (system).

Source

auto-restart.asd.

Child Component

auto-restart.lisp (file).


3 Files

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


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

3.1 Lisp


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

3.1.1 auto-restart/auto-restart.asd

Source

auto-restart.asd.

Parent Component

auto-restart (system).

ASDF Systems

auto-restart.


3.1.2 auto-restart/auto-restart.lisp

Source

auto-restart.asd.

Parent Component

auto-restart (system).

Packages

auto-restart.

Public Interface

with-auto-restart (macro).

Internals

4 Packages

Packages are listed by definition order.


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

4.1 auto-restart

Source

auto-restart.lisp.

Use List
  • common-lisp.
  • iterate.
Public Interface

with-auto-restart (macro).

Internals

5 Definitions

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


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

5.1 Public Interface


5.1.1 Macros

Macro: with-auto-restart ((&key retries sleep restart-name) &body body)
Package

auto-restart.

Source

auto-restart.lisp.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *attempt*
Package

auto-restart.

Source

auto-restart.lisp.


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

5.2.2 Ordinary functions

Function: call-with-auto-restart (restart-name fn)
Package

auto-restart.

Source

auto-restart.lisp.

Function: fix-args-for-funcall (var-names)
Package

auto-restart.

Source

auto-restart.lisp.


5.2.3 Conditions

Condition: restart-already-defined

When calling with-auto-restart, we expect the restart to be defined inside the body, not before it.

Package

auto-restart.

Source

auto-restart.lisp.

Direct superclasses

error.

Direct slots
Slot: restart-name
Package

common-lisp.

Initargs

:restart-name


Appendix A Indexes


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

A.1 Concepts


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

A.3 Variables

Jump to:   *  
R   S  
Index Entry  Section

*
*attempt*: Private special variables

R
restart-name: Private conditions

S
Slot, restart-name: Private conditions
Special Variable, *attempt*: Private special variables

Jump to:   *  
R   S