R: Create an R-level Task Callback Manager

taskCallbackManager {base} | R Documentation

## Create an R-level Task Callback Manager

### Description

This provides an entirely R-language mechanism for managing callbacks or actions that are invoked at the conclusion of each top-level task. Essentially, we register a single R function from this manager with the underlying, native task-callback mechanism and this function handles invoking the other R callbacks under the control of the manager. The manager consists of a collection of functions that access shared variables to manage the list of user-level callbacks.

### Usage

    taskCallbackManager(handlers = list(), registered = FALSE,
                        verbose = FALSE)

### Arguments

`handlers` | this can be a list of callbacks in which each element is a list with an element named `"f"` which is a callback function, and an optional element named `"data"` which is the 5-th argument to be supplied to the callback when it is invoked. Typically this argument is not specified, and one uses `add` to register callbacks after the manager is created.
`registered` | a logical value indicating whether the `evaluate` function has already been registered with the internal task callback mechanism. This is usually `FALSE` and the first time a callback is added via the `add` function, the `evaluate` function is automatically registered. One can control when the function is registered by specifying `TRUE` for this argument and calling `addTaskCallback` manually.
`verbose` | a logical value, which if `TRUE`, causes information to be printed to the console about certain activities this dispatch manager performs. This is useful for debugging callbacks and the handler itself.

### Value

A `list` containing 6 functions:

``add()`` | register a callback with this manager, giving the function, an optional 5-th argument, an optional name by which the callback is stored in the list, and a `register` argument which controls whether the `evaluate` function is registered with the internal C-level dispatch mechanism if necessary.
``remove()`` | remove an element from the manager's collection of callbacks, either by name or position/index.
``evaluate()`` | the ‘real’ callback function that is registered with the C-level dispatch mechanism and which invokes each of the R-level callbacks within this manager's control.
``suspend()`` | a function to set the suspend state of the manager. If it is suspended, none of the callbacks will be invoked when a task is completed. One sets the state by specifying a logical value for the `status` argument.
``register()`` | a function to register the `evaluate` function with the internal C-level dispatch mechanism. This is done automatically by the `add` function, but can be called manually.
``callbacks()`` | returns the list of callbacks being maintained by this manager.

### References

Duncan Temple Lang (2001) Top-level Task Callbacks in R, https://developer.r-project.org/TaskHandlers.pdf

### See Also

`addTaskCallback`, `removeTaskCallback`, `getTaskCallbackNames` and the reference.

### Examples

    # create the manager
    h <- taskCallbackManager()

    # add a callback
    h$add(function(expr, value, ok, visible) {
                           cat("In handler\n")
                           return(TRUE)
                         }, name = "simpleHandler")

    # look at the internal callbacks.
    getTaskCallbackNames()

    # look at the R-level callbacks
    names(h$callbacks())

    removeTaskCallback("R-taskCallbackManager")

[Package base version 4.0.5 Index]