weak_map 1.2.1

  • Readme
  • Changelog
  • Example
  • Installing
  • 91

pub package

weak_map #

This package contains the classes:

  • WeakMap
  • WeakContainer

And also the functions:

  • cache1_0
  • cache1_1
  • cache1_2
  • cache2_0
  • cache2_1
  • cache2_2

Why is this package useful? #

  1. Dart doesn't allow for real weak-references, but this package allows you to go as close as possible (internally it uses the Expando class). The Dart engine stores a value in memory while it is reachable (and can potentially be used). Usually, keys in a map are considered reachable and kept in memory while the map itself is in memory. This means if we put an object into a map or into a variable, then while the map is alive, the object will be alive as well, even if there are no other references to it. It occupies memory and may not be garbage collected. WeakMap and WeakContainer are fundamentally different in this aspect. They don't prevent garbage-collection of key objects.

  2. Caches that keep the result of expensive processes calculated over immutable data can also benefit from weak-maps. I here provide functions similar to the ones of the reselect package, but better. This can be used with Redux or with any other calculations over immutable data.


WeakMap #

A WeakMap lets you garbage-collect its keys. Please note the keys can be garbage-collected, not their corresponding values.

This means if you use some object as a key to a map-entry, this alone will not prevent Dart to garbage-collect this object.

In other words, after all other references to that object have been destroyed, its entry (key and value) may be removed automatically from the map at any moment. To create a map:

var map = WeakMap();

To add and retrieve a value:

map["John"] = 42;
var age = map["John"];

The following map methods work as expected:

map.remove("John")
map.clear()
map.contains("John"))

However, adding some null value to the map is the same as removing the key:

map["John"] = null; // Same as map.remove("John")

Notes:

  1. If you add a number, a boolean, a String, or a const type to the map, it will act like a regular map, because these types are never garbage-collected. All other types of object may be garbage-collected.

  2. To retrieve a value added to the map, you can use the equivalent syntaxes var y = map[x] or var y = map.get(x).

  3. Doing map[x] = y is equivalent to map.add(key: x, value: y), but the object is later retrieved by identity.


WeakContainer #

As previously explained, Dart doesn't have real weak-references. But you can check that some object is the same you had before.

To create a weak-container:

var obj = Object();
var ref = WeakContainer(obj);
var someObj = Random().nextBool() ? obj : Object();
print(ref.contains(someObj)); // True or false.

This will print true if someObj is the same as the original obj, and will print false if it's a different object, compared by identity. If all references to the original obj have been destroyed, the weak-container will not prevent obj to be garbage-collected.


Why doesn't Dart allow for real weak-references, anyway? #

Because the creators of Dart don't want the GC (garbage-collector) to be "visible".

Expandos are not equivalent to weak-references (meaning the Java WeakReference behavior). A weak reference is one that doesn't keep the referenced object alive, so the weak reference value may change to null at any time in the program. This makes the GC visible in the program.

Expandos are maps (from key to value) which won't keep the key alive. There is no way to distinguish an Expando that garbage collects the entry when the key dies, and one that doesn't, because you don't have the key to do the lookup anymore.

Basically, it means that an expando keeps a value alive as long as you have a reference to both the expando and the key, and after that, you can't check if the entry is there or not. With expandos, the GC need not be part of the language specification. It's just an optimization that implementations (are expected to) do to release memory that isn't needed anymore. Disabling the GC will not change the behavior of programs unless they run out of memory.


Cache #

Suppose you have some immutable information, which we call "state", and some parameters. We want to perform some expensive process (calculation, selection filtering etc) over the state, and we want to cache the result.

For example, suppose you want to filter an immutable list of millions of users, to create a new list with only the names that start with some text. You could filter the users list to remove all other names, like this:

List<User> filter(String text) => users.where((user)=>user.name.startsWith(text)).toList();

This is an expensive process, so you may want to cache the filtered list.

In this example, we have a single state and a single parameter, so we're going to use the cache1_1 method:

static List<User> filter(Users users, String text)
   => _filter(users)(text);

static final _filter = cache1_1(
        (Users users) 
           => (String text) 
              => users.where((user)=>user.name.startsWith(text)).toList());

The above code will calculate the filtered list only once, and then return it when the filter function is called again with the same users and text.

If the function is called with a different users and/or text, it will recalculate and cache the new result.

However, it treats the state and the parameter differently. If you call the function while keeping the same state and changing only the parameter, it will cache all the results, one for each parameter.

However, as soon as you call the function with a changed state, it will delete all of its previous cached information, since it understands that they are no longer useful. And even if you don't call that function ever again, it will delete the cached information if it detects that the state is no longer used in other parts of the program. In other words, it keeps the cached information in a weak-map, so that the cache will not hold to old information and have a negative impact in memory usage.

For the moment, the following six methods are provided, which combine 1 or 2 states with 0, 1 or 2 parameters:

cache1_0((state) => () => ...);
cache1_1((state) => (parameter) => ...);
cache1_2((state) => (parameter1, parameter2) => ...);
cache2_0((state1, state2) => () => ...);
cache2_1((state1, state2) => (parameter) => ...);
cache2_2((state1, state2) => (parameter1, parameter2) => ...);

I have created only those above, because for my own usage I never required more than that. Please, open an issue to ask for more variations in case you feel the need.

Note: These cache functions are similar to the "createSelector" functions found in the reselect package. The differences are: First, here you can keep any number of cached results for each function, one for each time the function is called with the same state and different parameters. Meanwhile, the reselect package only keeps a single cached result per function. Second, here it discards the cached information when the state changes or is no longer used in other parts of the program. Meanwhile, the reselect package will always keep the states and cached results in memory.



The Flutter packages I've authored:

My Medium Articles:

My article in the official Flutter documentation:


Marcelo Glasberg:
https://github.com/marcglasberg
https://twitter.com/glasbergmarcelo
https://stackoverflow.com/users/3411681/marcg
https://medium.com/@marcglasberg

[1.2.1] - 2020/06/12 #

  • Cache functions.

[1.1.2] - 2020/05/26 #

  • Add is by identity.
  • Docs improvement.

[1.0.6] - 2020/05/19 #

  • Removed dependency on Flutter (it's now pure Dart).

[1.0.2] - 2020/05/18 #

  • Example.

[1.0.0] - 2020/05/18 #

  • WeakMap and WeakContainer.

example/main.dart

import 'package:weak_map/weak_map.dart';

void main() {
  var map = WeakMap();
  map["A"] = 1;
  print('A = ${map["A"]}'); // A = 1
  print('B = ${map["B"]}'); // B = null

  var value = WeakContainer("X");
  print('Contains X = ${value.contains("X")}'); // Contains X = true
  print('Contains Y = ${value.contains("Y")}'); // Contains Y = false
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  weak_map: ^1.2.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:weak_map/weak_map.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
87
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
90
Overall:
Weighted score of the above. [more]
91
Learn more about scoring.

We analyzed this package on Jul 9, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14

Health suggestions

Fix lib/src/cache.dart. (-0.50 points)

Analysis of lib/src/cache.dart reported 1 hint:

line 61 col 11: DO use curly braces for all flow control structures.

Format lib/src/weak_container.dart.

Run dartfmt to format lib/src/weak_container.dart.

Format lib/src/weak_map.dart.

Run dartfmt to format lib/src/weak_map.dart.

Maintenance issues and suggestions

Support latest dependencies. (-10 points)

The version constraint in pubspec.yaml does not support the latest published versions for 1 dependency (meta).

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.7.0 <3.0.0
meta 1.1.8 1.1.8 1.2.2
Dev dependencies
test 1.14.3