Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the auto-restart Reference Manual, version 0.0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 03:20:44 2022 GMT+0.
• Introduction | What auto-restart is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
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.
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.
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.
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.
Built by Arnold Noronha arnold@tdrhq.com
Licensed under the Mozilla Public License, v2.
Next: Files, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The auto-restart system |
Arnold Noronha <arnold@jipr.io>
Apache License, Version 2.0
automatically generate restart-cases for the most common use cases, and also use the restart for automatic retries
0.0.1
iterate
auto-restart.asd (file)
auto-restart.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
• The auto-restart.asd file | ||
• The auto-restart/auto-restart.lisp file |
Next: The auto-restart/auto-restart․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
auto-restart.asd
auto-restart (system)
Previous: The auto-restart․asd file, Up: Lisp files [Contents][Index]
auto-restart (system)
auto-restart.lisp
with-auto-restart (macro)
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The auto-restart package |
auto-restart.lisp (file)
with-auto-restart (macro)
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported macros |
Previous: Exported definitions, Up: Exported definitions [Contents][Index]
auto-restart.lisp (file)
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables | ||
• Internal functions | ||
• Internal conditions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
auto-restart.lisp (file)
Next: Internal conditions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
auto-restart.lisp (file)
auto-restart.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
When calling with-auto-restart, we expect the restart to be defined inside the body, not before it.
auto-restart.lisp (file)
error (condition)
:restart-name
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | A F L |
---|
Jump to: | A F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
Jump to: | C F M W |
---|
Jump to: | C F M W |
---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
Jump to: | *
R S |
---|
Index Entry | Section | ||
---|---|---|---|
| |||
* | |||
*attempt* : | Internal special variables | ||
| |||
R | |||
restart-name : | Internal conditions | ||
| |||
S | |||
Slot, restart-name : | Internal conditions | ||
Special Variable, *attempt* : | Internal special variables | ||
|
Jump to: | *
R S |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | A C P R S |
---|
Jump to: | A C P R S |
---|