R: Get and set finalizer (name)

finalizer {ff} | R Documentation

## Get and set finalizer (name)

### Description

The generic `finalizer` allows to get the current finalizer. The generic `finalizer<-` allows to set the current finalizer or to change an existing finalizer (but not to remove a finalizer).

### Usage

    finalizer(x, ...)
    finalizer(x, ...) <- value
    ## S3 method for class 'ff'
    finalizer(x, ...)
    ## S3 replacement method for class 'ff'
    finalizer(x, ...) <- value

### Arguments

`x` | an `ff` object
`value` | the name of the new finalizer
`...` | ignored

### Details

If an `ff` object is created a finalizer is assigned, it has the task to free ressources no longer needed, for example remove the ff file or free the C++ RAM associated with an open ff file. The assigned finalizer depends on the location of the ff file: if the file is created in `getOption(fftempdir)` it is considered considered temporary and has default finalizer `delete`, files created in other locations have default finalizer `close`. The user can override this either by setting `options("fffinalizer")` or by using argument `finalizer` when creating single `ff` objects. Available finalizer generics are "close", "delete" and "deleteIfOpen", available methods are `close.ff`, `delete.ff` and `deleteIfOpen.ff`.
In order to be able to change the finalizer before finalization, the finalizer is NOT directly passed to R's finalization mechanism `reg.finalizer` (an active finalizer can never be changed other than be executed). Instead the NAME of the desired finalizer is stored in the ff object and `finalize.ff_pointer` is passed to `reg.finalizer`. `finalize.ff_pointer` will at finalization-time determine the desired finalizer and call it.
There are two possible triggers for execution `finalize.ff_pointer`:

1. the garbage collection `gc` following removal `rm` of the ff object

2. closing R if `finonexit` was `TRUE` at ff creation-time, determined by `options("fffinonexit")` and ff argument `finonexit`

Furthermore there are two possible triggers for calling the finalizer

1. an explicit call to `finalize`

2. an explicit call to one of the finalizers `close`, `delete` and `deleteIfOpen`

The user can define custom finalizers by creating a generic function like `delete`, a ff_pointer method like `delete.ff_pointer` and a ff method for manual calls like `delete.ff`. The user then is responsible to take care of two things

1. adequate freeing of ressources

2. proper maintenance of the finalizer name in the ff object via `physical$finalizer`

`is.null(finalizer(ff))` indicates NO active finalizer, i.e. no pending execution of `finalize.ff_pointer` lurking around after call of `reg.finalizer`. This requires that

1. the `ff_pointer` method sets the finalizer name to `NULL`

2. the `ff` may change a non-NULL finalizer name to a different name but not change it to NULL

### Value

`finalizer` returns the name of the active finalizer or `NULL` if no finalizer is active.
`finalizer<-` returns the changed ff object (reassignment of this return value not needed to keep the change). If there was no pending call to `finalize.ff_pointer` (`is.null(finalizer(ff))`), `finalizer<-` will create one by calling `reg.finalizer` with the current setting of `physical$finonexit`.

### Note

You can not assign NULL to an active finalizer using `finalizer<-` because this would not stop R's finalization mechanism and would carry the risk of assiging MULTIPLE finalization tasks.

### Author(s)

Jens Oehlschlägel

### See Also

`ff`, `finalize`, `reg.finalizer`

### Examples

      x <- ff(1:12, pattern="./finalizerdemo")
      fnam <- filename(x)
      finalizer(x)
      finalizer(x) <- "delete"
      finalizer(x)
      rm(x)
      file.exists(fnam)
      gc()
      file.exists(fnam)

[Package ff version 2.2-13 Index]