checkMemoryCache: Check the in-memory cache for matrix instances

In LTLA/beachmat: Compiling Bioconductor to Handle Each Matrix Type

Check the in-memory cache for matrix instances

Description

Check the in-memory cache for a pre-existing initialized C++ object, and initialize it if it does not exist. This is typically used in initializeCpp methods of file-backed representations to avoid redundant reads of the entire matrix.

Usage

flushMemoryCache()

checkMemoryCache(namespace, key, fun)

Arguments

namespace	String containing the namespace, typically the name of the package implementing the method.
key	String containing the key for a specific matrix instance.
fun	Function that accepts no arguments and returns an external pointer like those returned by initializeCpp.

Details

For representations where data extraction is costly (e.g., from file), initializeCpp methods may provide a memorize= option. Setting this to TRUE will load the entire matrix into memory, effectively paying a one-time up-front cost to improve efficiency for downstream operations that pass through the matrix multiple times.

If this option is provided, initializeCpp methods are expected to cache the in-memory instance using checkMemoryCache. This ensures that all subsequent calls to the same initializeCpp method will return the same instance, avoiding redundant memory loads when the same matrix is used in multiple functions.

Of course, this process saves time at the expense of increased memory usage. If too many instances are being cached, they can be cleared from memory using the flushMemoryCache function.

Value

For checkMemoryCache, the output of fun (possibly from an existing cache) is returned.

For flushMemoryCache, all existing cached objects are removed and NULL is invisibly returned.

Author(s)

Aaron Lun

Examples

# Mocking up a class with some kind of uniquely identifying aspect.
setClass("UnknownMatrix", slots=c(contents="dgCMatrix", uuid="character"))
X <- new("UnknownMatrix", 
    contents=Matrix::rsparsematrix(10, 10, 0.1), 
    uuid=as.character(sample(1e8, 1)))

# Defining our initialization method.
setMethod("initializeCpp", "UnknownMatrix", function(x, ..., memorize=FALSE) {
    if (memorize) {
        checkMemoryCache("my_package", x@uuid, function() initializeCpp(x@contents))
    } else {
        initializeCpp(x@contents)
    }
})

# Same pointer is returned multiple times.
initializeCpp(X, memorize=TRUE)
initializeCpp(X, memorize=TRUE)

# Flushing the cache.
flushMemoryCache()

LTLA/beachmat documentation built on Nov. 15, 2024, 10:19 p.m.