finalizer {ff}

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)