MemoizedFunction

Call memoized function and cache results

Description

A MemoizedFunction object maintains the memoization semantics of a function handle and a cache of the function call results. It has the same calling syntax as the function handle specified in the Function property. However, the MemoizedFunction object is not a function handle.

The first time you call the memoized function with a certain set of input values, MATLAB^® executes the function specified by the Function property and caches the results. In later calls to the memoized function with the same set of inputs, MATLAB returns the cached results instead of executing the function again.

The MemoizedFunction object maintains the cache of inputs and the corresponding outputs. When it is invoked, MATLAB returns the associated cached output values if the following conditions are true.

1. The input arguments are numerically equal to cached inputs. When comparing input values, MATLAB treats NaNs as equal.

2. The number of requested output arguments matches the number of cached outputs associated with the inputs.

Caution

A MemoizedFunction object is not aware of updates to the underlying function. If you modify the function associated with the memoized function, clear the cache with the clearCache object function.

Creation

To create a MemoizedFunction object, call the memoize function.

The memoization of a function is associated with the input function and not with the MemoizedFunction object. Therefore, keep the following in mind.

• Constructing a new MemoizedFunction object to the same function creates another reference to the same data. Two variables that memoize the same function share a cache and object property values, such as cache size. In the following example, the variables a and b share a cache and have the same value for cache size.

  a = memoize(@svd);
  b = memoize(@svd);

  Similarly, clearing the cache for b (b.clearCache) also clears the cache for a, and any other variables that memoize the svd function. clearCache is a MemoizedFunction object function.

• Assigning a MemoizedFunction object to a new variable creates another reference to the same data. In the following example, the variables c and d share data.

  c = memoize(@svd);
  d = c;

• Clearing a variable does not clear the cache associated with the input function. To clear the cache for a MemoizedFunction object that no longer exists in the workspace, create a new MemoizedFunction object to the same function, and use the clearCache function on the new object. Alternatively, you can clear caches for all MemoizedFunction objects using the clearAllMemoizedCaches function.

Properties

MemoizedFunction properties control the behavior of the memoized function. You can access or modify properties of the memoized function. Use dot notation to refer to a particular object and property:

m = memoize(@ones);
m.CacheSize = 25;

Function — Function with memoization semantics applied

function handle

Function with memoization semantics applied, returned as a function handle. This property is read only.

Data Types: function_handle

CacheSize — Maximum number of cached input and output combinations

10 (default) | positive integer

Maximum number of cached input and output combinations, specified as a positive integer.

Data Types: double

Enabled — Caching state

true (default) | false

Caching state, specified as true or false. To instruct MATLAB to call the function specified by the Function property regardless of whether the results are cached, and not to cache results, set this property to false.

Data Types: logical

Object Functions

clearCache	Clear cache for MemoizedFunction object
stats	Return cached values and statistics for MemoizedFunction object

Examples

Change Cache Size of Memoized Function

Create a MemoizedFunction object by memoizing the datetime function.

mf = memoize(@datetime)

mf = 
  MemoizedFunction with properties:

     Function: @datetime
      Enabled: 1
    CacheSize: 10

Change the maximum number of cached input and output combinations.

mf.CacheSize = 2

mf = 
  MemoizedFunction with properties:

     Function: @datetime
      Enabled: 1
    CacheSize: 2

Call the memoized function with three different input values.

a = mf('today');
b = mf('yesterday');
c = mf('tomorrow');

Call the stats function to investigate the cached results.

s = stats(mf);
s.Cache.Inputs{:}

ans = 1x1 cell array
    {'yesterday'}

ans = 1x1 cell array
    {'tomorrow'}

The results of calling the memoized function with 'today' are not cached because the CacheSize is 2.

Disable Memoization

In your current working folder, create the following file memoizeSquareExample.m that contains a function to compute the square of a number. When the function is called, if MATLAB returns cached results, msg is not displayed.

type memoizeSquareExample.m

function m = memoizeSquareExample(n)

m = n^2;
msg = "The square of " + string(n) + " is " + string(m) +".";
disp(msg)

end

Memoize the function. By default, memoization is enabled.

mf = memoize(@memoizeSquareExample);

Call the memoized function twice with the same input value. msg is displayed only once because the second function call returns cached results.

a = mf(42);

The square of 42 is 1764.

b = mf(42);

Disable memoization and call the memoized function with a repeat input value. Although the results for an input of 42 are cached, msg is displayed because memoization is disabled.

mf.Enabled = false;
c = mf(42);

The square of 42 is 1764.

Call the memoized function with a different set of inputs.

d = mf(13);

The square of 13 is 169.

Call the stats function to investigate the cached results. MATLAB does not return cached results while memoization is disabled or collect statistics, it continues to store input and output values.

s = mf.stats();
s.Cache.Inputs{:}

ans = 1x1 cell array
    {[42]}

Version History

Introduced in R2017a