taskCallbackManager           package:base           R Documentation

_C_r_e_a_t_e _a_n _R-_l_e_v_e_l _t_a_s_k _c_a_l_l_b_a_c_k _m_a_n_a_g_e_r

_D_e_s_c_r_i_p_t_i_o_n:

     This provides an entirely S-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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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. 

_V_a_l_u_e:

     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.

_N_o_t_e:

     This is an experimental feature and the interface may be changed
     in the future.

_S_e_e _A_l_s_o:

     'addTaskCallback', 'removeTaskCallback', 'getTaskCallbackNames'\
     <URL: http://developer.r-project.org/TaskHandlers.pdf>

_E_x_a_m_p_l_e_s:

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

     getTaskCallbackNames()
     removeTaskCallback("R-taskCallbackManager")