shiny/man/observe.Rd

% Generated by roxygen2 (4.0.0): do not edit by hand
\name{observe}
\alias{observe}
\title{Create a reactive observer}
\usage{
observe(x, env = parent.frame(), quoted = FALSE, label = NULL,
  suspended = FALSE, priority = 0)
}
\arguments{
  \item{x}{An expression (quoted or unquoted). Any return
  value will be ignored.}

  \item{env}{The parent environment for the reactive
  expression. By default, this is the calling environment,
  the same as when defining an ordinary non-reactive
  expression.}

  \item{quoted}{Is the expression quoted? By default, this
  is \code{FALSE}.  This is useful when you want to use an
  expression that is stored in a variable; to do so, it
  must be quoted with `quote()`.}

  \item{label}{A label for the observer, useful for
  debugging.}

  \item{suspended}{If \code{TRUE}, start the observer in a
  suspended state.  If \code{FALSE} (the default), start in
  a non-suspended state.}

  \item{priority}{An integer or numeric that controls the
  priority with which this observer should be executed. An
  observer with a given priority level will always execute
  sooner than all observers with a lower priority level.
  Positive, negative, and zero values are allowed.}
}
\value{
An observer reference class object. This object has the following
  methods:
  \describe{
    \item{\code{suspend()}}{
      Causes this observer to stop scheduling flushes (re-executions) in
      response to invalidations. If the observer was invalidated prior to
      this call but it has not re-executed yet then that re-execution will
      still occur, because the flush is already scheduled.
    }
    \item{\code{resume()}}{
      Causes this observer to start re-executing in response to
      invalidations. If the observer was invalidated while suspended, then it
      will schedule itself for re-execution.
    }
    \item{\code{setPriority(priority = 0)}}{
      Change this observer's priority. Note that if the observer is currently
      invalidated, then the change in priority will not take effect until the
      next invalidation--unless the observer is also currently suspended, in
      which case the priority change will be effective upon resume.
    }
    \item{\code{onInvalidate(callback)}}{
      Register a callback function to run when this observer is invalidated.
      No arguments will be provided to the callback function when it is
      invoked.
    }
  }
}
\description{
Creates an observer from the given expression.
}
\details{
An observer is like a reactive
expression in that it can read reactive values and call reactive expressions, and
will automatically re-execute when those dependencies change. But unlike
reactive expressions, it doesn't yield a result and can't be used as an input
to other reactive expressions. Thus, observers are only useful for their side
effects (for example, performing I/O).

Another contrast between reactive expressions and observers is their execution
strategy. Reactive expressions use lazy evaluation; that is, when their
dependencies change, they don't re-execute right away but rather wait until
they are called by someone else. Indeed, if they are not called then they
will never re-execute. In contrast, observers use eager evaluation; as soon
as their dependencies change, they schedule themselves to re-execute.
}
\examples{
values <- reactiveValues(A=1)

obsB <- observe({
  print(values$A + 1)
})

# Can use quoted expressions
obsC <- observe(quote({ print(values$A + 2) }), quoted = TRUE)

# To store expressions for later conversion to observe, use quote()
expr_q <- quote({ print(values$A + 3) })
obsD <- observe(expr_q, quoted = TRUE)

# In a normal Shiny app, the web client will trigger flush events. If you
# are at the console, you can force a flush with flushReact()
shiny:::flushReact()
}