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)

Arguments

cnd

A condition object (see cnd()).

.cnd, .mufflable

These arguments are retired. .cnd has been renamed to cnd and .mufflable no longer has any effect as non-critical conditions are always signalled with a muffling restart.

Details

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()).

Lifecycle

  • 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.

See also

abort(), warn() and inform() for signalling typical R conditions. See with_handlers() for establishing condition handlers.

Examples

# 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"