async_debug: Async debugging utilities

In r-lib/async: Asynchronous Computation and 'I/O'

Async debugging utilities

Description

Helper function to help with the non-trivial debugging of async code.

Usage

async_next(el = NULL)

async_step()

async_step_back()

async_list(def = NULL)

async_tree(def = NULL)

async_debug(id, action = TRUE, parent = TRUE)

async_wait_for(id)

async_where(
  calls = sys.calls(),
  parents = sys.parents(),
  frm = get_async_frames()
)

async_debug_shortcuts()

async_debug_remove_shortcuts()

Arguments

el	Event loop, defaults to the current event loop.
def	Deferred value that is used at the root of the DAG. Defaults to the deferred value corresponding to the result of the async phase.
id	Integer scalar, the if of the deferred to debug or to wait for.
action	Whether to debug the action callback.
parent	Whether to debug the parent callbacks.
calls	The calls to print, result of sys.calls(). Defaults to the current call stack.
parents	The parent frames in the call stack, result of sys.parents(). Defaults to the current parents.
frm	The async frame to mark. Defaults to the most recent async frame in the stack.

Details

Async debugging can be turned on by setting the async_debug global option to TRUE:

options(async_debug = TRUE)

Setting this value to FALSE will turn off debugging.

If debugging is on, a synchronise() call will stop at the beginning of the event loop. No deferred actions of other callbacks have run at this point. synchronise() stops by calling base::browser(). All the usual browser() commands (see its manual) can be used here, plus some extra commands to help async debugging. The extra commands:

async_debug_shortcuts() adds handy shortcuts to most of the helper functions. E.g. async_next() can be invoked as .an (without the parens). You only need to run it once per R session. Note that it adds the shortcuts to the global environment.

async_debug_remove_shortcuts() removes the shortcuts from the global environment.

.an (or async_next()) runs the next iteration of the event loop. Note that it does not return until something happens in the event loop: an action or a parent callback is executed, or HTTP or other I/O is performed. Also note, that a single iteration of the event loop typically runs multiple action, parent or other callbacks. Once the iteration is done, the control is returned to the browser.

.as (or async_step()) is similar to .an, but it also starts the debugging of the action or parent callbacks. I.e. another browser() is called at the beginning of all callbacks in the next iteration of the event loop.

.asb (or async_step_back()) stops the debugging of the callbacks. It does not actually exdecutes anything from the event loop, so to go back to the main async browser, you also need to execute c (continue).

.al (or async_list()) lists all deferred values in the current async phase. (Only the ones that already exist, some may be created in the future.) It returns a data frame with columns:

• id: The integer id of the deferred value.

• parents: Integer vector, the parents of the deferred value.

• label: A character label, that is used by async_tree() to nicely format information about a deferred value.

• call: The call (language object) that created the deferred value.

• children: The list of children, an integer vector. A deferred value can only have one child, unless it is shared.

• type: The type of the deferred value. This is an arbitrary label, specified when the deferred value was created.

• running: Whether the deferred value is already running.

• state: The state of the deferred value, "pending", "fulfilled" or "rejected". This is typically pending, since resolved deferred values are removed from the async DAG (in the next event loop iteration.)

• cancelled: Whether the deferred value was cancelled.

• shared: Whether the deferred value is shared.

• filename: The file name for the source code that created the deferred value. Only present if this code was parsed with source references enabled.

• position: The start file position, in line:column format, as a string. Only present if this code was parsed with source references enabled.

.at (or async_tree()) prints the DAG of the deferred values.

async_debug() can be used to debug the action and/or parent callbacks of the specified deferred value.

async_wait_for() runs the event loop until the specified deferred value is resolved (i.e. fulfilled or rejected).

.aw (or async_where()) prints a call stack and marks the frame the corresponds to an action or parent callback.

r-lib/async documentation built on March 24, 2024, 6:20 p.m.