R6.Rmd

# R6

This chapter describes the R6 object system. Unlike S3 and S4, it provides encapsulated OO, which means that:

* R6 methods belong to objects, not generics.

* R6 objects are mutable: the usual copy-on-modify semantics do not apply.

These properties make R6 objects behave more like objects in programming languages such as Python, Ruby and Java. This does not mean that R6 is good, and S3 and S4 are bad, it just means that R has a different heritage than most modern mainstream programming languages.

R6 is very similar to a built-in OO system called __reference classes__, or RC for short. I'm going to teach you R6 instead of RC for four reasons:

* R6 is much simpler. Both R6 and RC are built on top of environments, but
  while R6 uses S3, RC uses S4. R6 is only ~500 lines of R code (and ~1700 
  lines of tests!). We're not going to discuss the implementation in depth
  here, but if you've mastered the contents of this book, you should be able
  to read the source code and figure out how it works.

* RC mingles variables and fields in the same stack of environments so that you
  get (`field`) and set fields (`field <<- value`) like regular values. R6 puts 
  fields in a separate environment so you get (`self$field`) and set 
  (`self$field <- value`) with a prefix. The R6 approach is more verbose but is
  worth the tradeoff because it makes code easier to understand. It also makes 
  inheritance across packages simpler and more robust.

* R6 is much faster than RC. Generally, the speed of method dispatch is not 
  important outside of microbenchmarks but R6 is substantially better than
  RC. Switching from RC to R6 yielded substantial performance in shiny. 
  `vignette("Performance", "R6")` provides more details on the performance.

* Because the ideas that underlie R6 and RC are similar, it will only require 
  a small amount of additional effort to learn R6 if you need to.

Because R6 is not built into base R, you'll need to install and load a package in order to use it:

```{r setup}
library(R6)
```

## Classes and methods

R6 only needs a single function call to create both the class and its methods: `R6::R6Class()`. And this is the only function from the package that you'll ever use! The following example shows the two most important arguments:

* The first argument is the `classname`. It's not strictly needed, but it
  improves error messages and makes it possible to also use R6 objects
  with S3 generics. By convention, R6 classes use UpperCamelCase.
  
* The second argument, `public`, supplies a list of methods (functions) and 
  fields (anything else) that make up the public interface of the object. 
  By convention, methods and fields use snake_case. Methods can access
  the methods and fields of the current object via `self$`.

```{r}
Accumulator <- R6Class("Accumulator", list(
  sum = 0,
  add = function(x = 1) {
    self$sum <- self$sum + x 
    invisible(self)
  })
)
```

You should always assign the result of `R6Class()` into a variable with the same name as the class. This creates an R6 object that defines the R6 class:

```{r}
Accumulator
```

You construct a new object from the class by calling the `new()` method. Methods belong to R6 objects so you use `$` to access `new()`:

```{r}
x <- Accumulator$new() 
```

You can then call methods and access fields with `$`:

```{r}
x$add(4) 
x$sum
```

In this class, the fields and methods are public which means that you can get or set the value of any field. Later, we'll see how to use private fields and methods to prevent casual access to the internals of your class.

To make it clear when we're talking about fields and methods as opposed to variables and functions, when referring to them in text, we'll prefix with `$`. For example, the `Accumulate` class has field `$sum` and method `$add()`.

### Method chaining

`$add()` is called primarily for its side-effect of updating `$sum`. 

```{r}
Accumulator <- R6Class("Accumulator", list(
  sum = 0,
  add = function(x = 1) {
    self$sum <- self$sum + x 
    invisible(self)
  })
)
```

Side-effect R6 methods should always return `self` invisibly. This returns the "current" object and makes it possible to chain together multiple method calls:

```{r}
x$add(10)$add(10)$sum
```

Alternatively, for long chains, you can spread the call over multiple lines:

```{r}
x$
  add(10)$
  add(10)$
  sum
```

This technique is called __method chaining__ and is commonly used in encapsulated OO languages (like Python and JavaScript) to create fluent interfaces. Method chaining is deeply related to the pipe, and we'll discuss the pros and cons of each approach in [pipe vs message-chaining tradeoffs](#tradeoffs-pipe).

### Important methods

There are two important methods that will be defined for most classes: `$initialize()` and `$print()`. You don't have to provide them, but it's a good idea to do so because they will make your class easier to use.

`$initialize()` overrides the default behaviour of `$new()`. For example, the following code defines an R6 Person class, similar to the S4 equivalent in [S4]. Unlike S4, R6 provides no checks for object type by default. `$initialize()` is a good place to check that `name` and `age` are the correct types.

```{r}
Person <- R6Class("Person", list(
  name = NULL,
  age = NA,
  initialize = function(name, age = NA) {
    stopifnot(is.character(name), length(name) == 1)
    stopifnot(is.numeric(age), length(age) == 1)
    
    self$name <- name
    self$age <- age
  }
))

hadley <- Person$new("Hadley", age = 37)
```

If you have more expensive validation requirements, implement them in a separate `$validate()` and only call when needed.

Defining `$print()` allows you to override the default printing behaviour. As with any R6 method called for its side effects, `$print()` should return `invisible(self)`.

```{r}
Person <- R6Class("Person", list(
  name = NULL,
  age = NA,
  initialize = function(name, age = NA) {
    self$name <- name
    self$age <- age
  },
  print = function(...) {
    cat("Person: \n")
    cat("  Name: ", self$name, "\n", sep = "")
    cat("  Age:  ", self$age, "\n", sep = "")
    invisible(self)
  }
))

hadley2 <- Person$new("Hadley")
hadley2
```

This code illustrates an important aspect of R6. Because methods are bound to individual objects, the previously created `hadley` does not get this new method:

```{r}
hadley
```

Indeed, from the perspective of R6, there is no relationship between `hadley` and `hadley2`. This can make interactive experimentation with R6 confusing. If you're changing the code and can't figure out why the results of method calls aren't changed, make sure you've re-constructed R6 objects with the new class.

There's a useful alternative to `$print()`: implement `$format()`, which should return a character vector. This will automatically be used by both `print()` and `format()` S3 generics. 

```{r}
Person <- R6Class("Person", list(
  age = NA,
  name = NULL,
  initialize = function(name, age = NA) {
    self$name <- name
    self$age <- age
  },
  format = function(...) {
    # The first `paste0()` is not necessary but it lines up
    # with the subsequent lines making it easier to see how
    # it will print
    c(
      paste0("Person:"),
      paste0("  Name: ", self$name),
      paste0("  Age:  ", self$age)
    )
  }
))

hadley3 <- Person$new("Hadley")
format(hadley3)
hadley3
```

### Private fields and methods

With R6 you can define "private" fields and methods, elements that can only be accessed from within the class, but not from the outside. There are two things that you need to know to take advantage of private elements:

* The `private` argument works in the same way as the `public` argument:
  you give it a named list of methods (functions) and fields (everything else).
  
* Fields and methods defined in `private` are available within the methods
  with `private$` instead of `self$`. You cannot access private fields or
  methods outside of the class.
  
To make this concrete, we could make `$age` and `$name` fields of the Person class private. With this definition of `Person` we can only set `$age` and `$name` during object creation, and we cannot access their values from outside of the class.

```{r}
Person <- R6Class("Person", 
  public = list(
    initialize = function(name, age = NA) {
      private$name <- name
      private$age <- age
    },
    print = function(...) {
      cat("Person: \n")
      cat("  Name: ", private$name, "\n", sep = "")
      cat("  Age:  ", private$age, "\n", sep = "")
    }
  ),
  private = list(
    age = NA,
    name = NULL
  )
)

hadley4 <- Person$new("Hadley")
hadley4$name
```

The distinction between public and private fields is important when you create complex networks of classes, and you want to make it as clear as possible what it's ok for others to access. Anything that's private can be more easily refactored because you know others aren't relying on it. Private methods tend to be more important in other programming languages compared to R because the object hierarchies in R tend to be simpler.

### Active fields
Public fields allows direct access to the data they contains. There is no control, or validation, when their value is being modified, so their use can be inherently unsafe (in the sense that your program could fail). An alternative to this is to implement specific setter and getter method for values while keeping the actual value private. As an example, we could add a job title to the Person class. As this could be subject to change we would like users to be able to change it after the object has been created, but we want to be able to ensure that only a string can be added to the field.

```{r}
Person <- R6Class("Person", 
  public = list(
    initialize = function(name, age = NA, job = NA) {
      private$name <- name
      private$age <- age
      private$job <- job
    },
    print = function(...) {
      cat("Person: \n")
      cat("  Name: ", private$name, "\n", sep = "")
      cat("  Age:  ", private$age, "\n", sep = "")
      cat("  job:  ", private$job, "\n", sep = "")
    },
    set_job = function(title) {
      stopifnot(length(title) == 1)
      stopifnot(is.character(title))
      private$job <- title
      invisible(self)
    },
    get_job = function() {
      private$job
    }
  ),
  private = list(
    age = NA,
    name = NULL,
    job = NA
  )
)

hadley5 <- Person$new("Hadley")
hadley5$set_job("R programmer")
hadley5$get_job()
```

While this provides a lot of control, it can become cumbersome to write separate setter and getter methods for each field. Furthermore, it masks the fact that the user is dealing with a field. An alternative approach is to use active fields, which are fields that calls a function when they are accessed and modified. Let's rewrite the class above.

```{r}
Person <- R6Class("Person", 
  public = list(
    initialize = function(name, age = NA, job = NA) {
      private$name <- name
      private$age <- age
      private$JOB <- job
    },
    print = function(...) {
      cat("Person: \n")
      cat("  Name: ", private$name, "\n", sep = "")
      cat("  Age:  ", private$age, "\n", sep = "")
      cat("  job:  ", private$JOB, "\n", sep = "")
    }
  ),
  active = list(
    job = function(value) {
      if (missing(value)) return(private$JOB)
      stopifnot(length(value) == 1)
      stopifnot(is.character(value))
      private$JOB <- value
    }
  ),
  private = list(
    age = NA,
    name = NULL,
    JOB = NA
  )
)

hadley6 <- Person$new("Hadley", job = "R programmer")
hadley6$job
hadley6$job <- "Bartender"
try(hadley6$job <- 10)
```

As can be seen the `job` field acts like any other field, except that it now contains its own validation logic. There is no limit to the code that can be put into the function of an active field. They can be used to provide read-only values as well as access to and modification of virtual values. As a last example, the `Person` class can be rewritten to make age read-only and provide an active field for the full name.

```{r}
Person <- R6Class("Person", 
  public = list(
    initialize = function(first_name, last_name, age = NA, job = NA) {
      private$first_name <- first_name
      private$last_name <- last_name
      private$AGE <- age
      private$JOB <- job
    },
    print = function(...) {
      cat("Person: \n")
      cat("  Name: ", private$last_name, ', ', private$first_name, "\n", sep = "")
      cat("  Age:  ", private$AGE, "\n", sep = "")
      cat("  job:  ", private$JOB, "\n", sep = "")
    }
  ),
  active = list(
    job = function(value) {
      if (missing(value)) return(private$JOB)
      stopifnot(length(value) == 1)
      stopifnot(is.character(value))
      private$JOB <- value
    },
    age = function() {
      private$AGE
    },
    full_name = function(value) {
      if (missing(value)) return(paste(private$first_name, private$last_name))
      all_names <- strsplit(value, ' ')[[1]]
      private$first_name <- all_names[1]
      private$last_name <- all_names[2]
    }
  ),
  private = list(
    AGE = NA,
    first_name = NULL,
    last_name = NULL,
    JOB = NA
  )
)

hadley7 <- Person$new("Hadley", "Wickham", age = 10)
hadley7$age
try(hadley7$age <- 20)
hadley7$full_name <- "John Doe"
hadley7
```

### Inheritance

To inherit behaviour from an existing class, provide the class object to the `inherit` argument:

```{r}
AccumulatorChatty <- R6Class("AccumulatorChatty", 
  inherit = Accumulator,
  public = list(
    add = function(x = 1) {
      cat("Adding ", x, "\n", sep = "")
      super$add(x = x)
    }
  )
)

x2 <- AccumulatorChatty$new()
x2$add(10)$add(1)$sum
```

Note that `$add()` overrides the implementation in the superclass, but we can access the previous implementation through `super$`. Any methods which do not override will automatically call the implementation in the parent class.

R6 only supports single inheritance: you cannot supply a vector of classes to inherit.

### Introspection

Every R6 object has an S3 class that reflects the hierarchy of R6 classes. This means that the easiest way to determine the class (and all classes it inherits from) is to use `class()`:

```{r}
class(hadley4)
```

The S3 hierarchy includes the base "R6" class. This provides common behaviour, including an `print.R6()` method which calls `$print()` or `$format()`, as described above.

You can list all methods and fields with `names()`:

```{r}
names(hadley4)
```

There's one method that we haven't defined: `$clone()`. It's provided by the R6 base class and we'll come back to it in the next section when we discuss the reference semantics that R6 objects possess.

There's no way to list private fields or methods from outside the class. They're private for a reason!

### Exercises

1.  Can subclasses access private fields/methods from their parent? Perform
    an experiment to find out.

## Reference semantics

One of the big differences between R6 and most other objects in R is that they have reference semantics. This is because they are S3 objects built on top of environments:

```{r}
typeof(x2)
```

The main consequence of reference semantics is that objects are not copied when modified:

```{r}
y1 <- Accumulator$new() 
y2 <- y1

y1$add(10)
y2$sum
```

You can manually copy an R6 object by calling `$clone()`.

```{r}
y1 <- Accumulator$new() 
y2 <- y1$clone()

y1$add(10)
y2$sum
```

There are three other less obvious consequences:

* It is harder to reason about code that uses R6 objects because you need to 
  understand more context.
  
* It makes sense to think about when an R6 object is deleted, and you
  can write a `finalizer()` to complement the `initializer()`.
  
* If one of the fields is an R6 class, you must call `$new()` inside
  `$initialize()` not inside `R6Class()`.
  
These three consequences are discussed in more detail below.

### Reasoning

Generally, reference semantics makes code harder to reason about. Take this very simple example:

```{r, eval = FALSE}
x <- list(a = 1)
y <- list(b = 2)

z <- f(x, y)
```

For the vast majority of functions, you know that the final line only modifies `z`.  

Take a similar equivalent that uses an imaginary `List` reference class:

```{r, eval = FALSE}
x <- List$new(a = 1)
y <- List$new(b = 2)

z <- f(x, y)
```

The final line is much harder to reason about - it's completely possible that `f()` calls methods of `x` or `y`, modifying them in place. This is the biggest potential downside of R6. The best way to ameliorate this problem is to avoid writing functions that both return a value and modify R6 inputs. 

That said, modifying R6 inputs can lead to substantially simpler code in some cases. One challenge of working with immutable data is known as __threading state__: if you want to return a value that's modified in a deeply nested function, you need to return the modified value up through every function. This can complicate code, particularly if you need to modify multiple values. For example, ggplot2 uses R6 objects for scales. Scales are complex because they need to combine data across every facet and every layer. Using R6 makes the code substantially simpler, at the cost of introducing subtle bugs. Fixing those bugs required careful placement of calls to `$clone()` to ensure that independent plots didn't accidentally share scale data.

### Finalizer

One useful property of reference semantics is that it makes sense to think about when an R6 object is __finalised__, or when it's deleted. This doesn't make sense for S3 and S4 objects because copy-on-modify semantics mean that there may be many transient versions of an object. For example, in the following code, there are actually two factor objects: the second is created when the levels are modified, leaving the first to be destroyed at the next garbage collection (GC).

```{r}
x <- factor(c("a", "b", "c"))
levels(x) <- c("c", "b", "a")
```

Since R6 objects are not copied-on-modify they will only get deleted once, and it makes sense to think about `$finalize()` as a complement to `$initialize()`. Finalizers usually play a similar role to `on.exit()`, cleaning up any resources created by the initializer. For example, the following class wraps up a temporary file, automatically deleting it when the class is finalised.

```{r}
TemporaryFile <- R6Class("TemporaryFile", list(
  path = NULL,
  initialize = function() {
    self$path <- tempfile()
  },
  finalize = function() {
    message("Cleaning up ", self$path)
    unlink(self$path)
  }
))

tf <- TemporaryFile$new()
```

The finalise method will be run when R exits, or by the first garbage collection after the object has been removed. Generally, this will happen when it happens, but it can occassionally be useful to force a run with an explicit call to `gc()`.

```{r}
rm(tf)
invisible(gc())
```

### R6 fields

A final consequence of reference semantics can crop up where you don't expect it. Beware of setting a default value to an R6 class: it will be shared across all instances of the object. This is because `$new()` is only called once when you defined the class, not each time you call new.

```{r}
TemporaryDatabase <- R6Class("TemporaryDatabase", list(
  con = NULL,
  file = TemporaryFile$new(),
  initialize = function() {
    DBI::dbConnect(RSQLite::SQLite(), path = file$path)
  }
))

db_a <- TemporaryDatabase$new()
db_b <- TemporaryDatabase$new()

db_a$file$path == db_b$file$path
```

You can fix this by creating the object in `$initialize()`:

```{r}
TemporaryDatabase <- R6Class("TemporaryDatabase", list(
  con = NULL,
  file = NULL,
  initialize = function() {
    self$file <- TemporaryFile$new()
    DBI::dbConnect(RSQLite::SQLite(), path = file$path)
  }
))

db_a <- TemporaryDatabase$new()
db_b <- TemporaryDatabase$new()

db_a$file$path == db_b$file$path
```

### Excercises


## Learning more

If you'd like to learn more about R6, the best place to start is the vignettes included in the package. You can list them by calling `browseVignettes(package = "R6")`.