Signal a condition to handlers that have been established on the
stack. Conditions signalled with cnd_signal() are assumed to be
benign. Control flow can resume normally once the condition has
been signalled (if no handler jumped somewhere else on the
evaluation stack). On the other hand, cnd_abort() treats the
condition as critical and will jump out of the distressed call
frame (see rst_abort()), unless a handler can deal with the
condition.
cnd_signal(cnd, .cnd, .mufflable)
| cnd | A condition object (see |
|---|---|
| .cnd, .mufflable | These arguments are retired. |
If .critical is FALSE, this function has no side effects beyond
calling handlers. In particular, execution will continue normally
after signalling the condition (unless a handler jumped somewhere
else via rst_jump() or by being exiting()). If .critical is
TRUE, the condition is signalled via base::stop() and the
program will terminate if no handler dealt with the condition by
jumping out of the distressed call frame.
calling() handlers are called in turn when they decline to handle
the condition by returning normally. However, it is sometimes
useful for a calling handler to produce a side effect (signalling
another condition, displaying a message, logging something, etc),
prevent the condition from being passed to other handlers, and
resume execution from the place where the condition was
signalled. The easiest way to accomplish this is by jumping to a
restart point (see with_restarts()) established by the signalling
function. cnd_signal() always installs a muffle restart (see
cnd_muffle()).
Modifying a condition object with cnd_signal() is defunct.
Consequently the .msg and .call arguments are retired and
defunct as of rlang 0.3.0. In addition .cnd is renamed to
cnd and soft-deprecated.
The .mufflable argument is soft-deprecated and no longer has
any effect. Non-critical conditions are always signalled with a
muffle restart.
Creating a condition object with cnd_signal() is
soft-deprecated. Please use signal() instead.
abort(), warn() and inform() for signalling typical
R conditions. See with_handlers() for establishing condition
handlers.
# Creating a condition of type "foo" cnd <- cnd("foo") # If no handler capable of dealing with "foo" is established on the # stack, signalling the condition has no effect: cnd_signal(cnd) # To learn more about establishing condition handlers, see # documentation for with_handlers(), exiting() and calling(): with_handlers(cnd_signal(cnd), foo = calling(function(c) cat("side effect!\n")) )#> side effect!#> NULL# By default, cnd_signal() creates a muffling restart which allows # calling handlers to prevent a condition from being passed on to # other handlers and to resume execution: undesirable_handler <- calling(function(c) cat("please don't call me\n")) muffling_handler <- calling(function(c) { cat("muffling foo...\n") cnd_muffle(c) }) with_handlers(foo = undesirable_handler, with_handlers(foo = muffling_handler, { cnd_signal(cnd("foo")) "return value" }))#> muffling foo...#> [1] "return value"