taskCallback              package:base              R Documentation

_A_d_d _o_r _r_e_m_o_v_e _a _t_o_p-_l_e_v_e_l _t_a_s_k _c_a_l_l_b_a_c_k

_D_e_s_c_r_i_p_t_i_o_n:

     'addTaskCallback' registers an R function that is to be called
     each time a top-level task is completed.

     'removeTaskCallback' un-registers a function that was registered
     earlier via 'addTaskCallback'.

     These provide low-level access to the internal/native mechanism
     for managing task-completion actions. One can use
     'taskCallbackManager' at the S-language level to manage S
     functions that are called at the completion of each task. This is
     easier and more direct.

_U_s_a_g_e:

     addTaskCallback(f, data = NULL, name = character(0))
     removeTaskCallback(id)

_A_r_g_u_m_e_n_t_s:

       f: the function that is to be invoked each time a top-level task
          is successfully completed. This is called with 5 or 4
          arguments depending on whether 'data' is specified or not,
          respectively. The return value should be a logical value
          indicating whether to keep the callback in the list of active
          callbacks or discard it.

    data: if specified, this is the 5-th argument in the call to the
          callback function 'f'.

      id: a string or an integer identifying the element in the
          internal callback list to be removed. Integer indices are
          1-based, i.e the first element is 1. The names of currently
          registered handlers is available using 'getTaskCallbackNames'
          and is also returned in a call to 'addTaskCallback'. 

    name: character: names to be used.

_D_e_t_a_i_l_s:

     Top-level tasks are individual expressions rather than entire
     lines of input. Thus an input line of the form 'expression1 ;
     expression2' will give rise to 2 top-level tasks.

     A top-level task callback is called with the expression for the
     top-level task, the result of the top-level task, a logical value
     indicating whether it was successfully completed or not (always
     TRUE at present), and a logical value indicating whether the
     result was printed or not. If the 'data' argument was specified in
     the call to 'addTaskCallback', that value is given as the fifth
     argument.

     The callback function should return a logical value. If the value
     is FALSE, the callback is removed from the task list and will not
     be called again by this mechanism. If the function returns TRUE,
     it is kept in the list and will be called on the completion of the
     next top-level task.

_V_a_l_u_e:

     'addTaskCallback' returns an integer value giving  the position in
     the list of task callbacks that this new callback occupies. This
     is only the current position of the callback. It can be used to
     remove the entry as long as no other values are removed from
     earlier positions in the list first.

     'removeTaskCallback' returns a logical value indicating whether
     the specified element was removed. This can fail (i.e., return
     'FALSE') if an incorrect name or index is given that does not
     correspond to the name or position of an element in the list.

_N_o_t_e:

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

     There is also C-level access to top-level task callbacks to allow
     C routines rather than R functions be used.

_S_e_e _A_l_s_o:

     'getTaskCallbackNames' 'taskCallbackManager' <URL:
     http://developer.r-project.org/TaskHandlers.pdf>

_E_x_a_m_p_l_e_s:

      times <- function(total = 3, str="Task a") {
        ctr <- 0

        function(expr, value, ok, visible) {
         ctr <<- ctr + 1
         cat(str, ctr, "\n")
         if(ctr == total) {
           cat("handler removing itself\n")
         }
         return(ctr < total)
        }
      }

      # add the callback that will work for
      # 4 top-level tasks and then remove itself.
      n <- addTaskCallback(times(4))

      # now remove it, assuming it is still first in the list.
      removeTaskCallback(n)

     ## Not run: 
     # There is no point in running this
     # as 
      addTaskCallback(times(4))

      sum(1:10)
      sum(1:10)
      sum(1:10)
      sum(1:10)
      sum(1:10)
     ## End(Not run)