ExtendedTask: add example to docs (#4087)

Co-authored-by: Garrick Aden-Buie <[email protected]>

NEWS.md

@@ -8,6 +8,8 @@
 
 * Improve collection of deep stack traces (stack traces that are tracked across steps in an async promise chain) with `coro` async generators such as `elmer` chat streams. Previously, Shiny treated each iteration of an async generator as a distinct deep stack, leading to pathologically long stack traces; now, Shiny only keeps/prints unique deep stack trace, discarding duplicates. (#4156)
 
+* Added an example to the `ExtendedTask` documentation. (@daattali #4087)
+
 ## Bug fixes
 
 * Fixed a bug in `conditionalPanel()` that would cause the panel to repeatedly show/hide itself when the provided condition was not boolean. (@kamilzyla, #4127)

R/extended-task.R

@@ -41,6 +41,54 @@
 #'   is, a function that quickly returns a promise) and allows even that very
 #'   session to immediately unblock and carry on with other user interactions.
 #'
+#' @examplesIf rlang::is_interactive() && rlang::is_installed("future")
+#'
+#' library(shiny)
+#' library(bslib)
+#' library(future)
+#' plan(multisession)
+#'
+#' ui <- page_fluid(
+#'   titlePanel("Extended Task Demo"),
+#'   p(
+#'     'Click the button below to perform a "calculation"',
+#'     "that takes a while to perform."
+#'   ),
+#'   input_task_button("recalculate", "Recalculate"),
+#'   p(textOutput("result"))
+#' )
+#'
+#' server <- function(input, output) {
+#'   rand_task <- ExtendedTask$new(function() {
+#'     future(
+#'       {
+#'         # Slow operation goes here
+#'         Sys.sleep(2)
+#'         sample(1:100, 1)
+#'       },
+#'       seed = TRUE
+#'     )
+#'   })
+#'
+#'   # Make button state reflect task.
+#'   # If using R >=4.1, you can do this instead:
+#'   # rand_task <- ExtendedTask$new(...) |> bind_task_button("recalculate")
+#'   bind_task_button(rand_task, "recalculate")
+#'
+#'   observeEvent(input$recalculate, {
+#'     # Invoke the extended in an observer
+#'     rand_task$invoke()
+#'   })
+#'
+#'   output$result <- renderText({
+#'     # React to updated results when the task completes
+#'     number <- rand_task$result()
+#'     paste0("Your number is ", number, ".")
+#'   })
+#' }
+#'
+#' shinyApp(ui, server)
+#'
 #' @export
 ExtendedTask <- R6Class("ExtendedTask", portable = TRUE, cloneable = FALSE,
   public = list(