From b838e3f899a81960460f4615a7c4d389ce8a6d51 Mon Sep 17 00:00:00 2001 From: David Little Date: Fri, 12 Apr 2024 10:53:30 -0400 Subject: [PATCH] Improve readme (#10) --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f6f283e..ddf8966 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,9 @@ [![CI](https://github.com/beacon-biosignals/WeakKeyIdDicts.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/beacon-biosignals/WeakKeyIdDicts.jl/actions/workflows/CI.yml?query=branch%3Amain) [![codecov](https://codecov.io/gh/beacon-biosignals/WeakKeyIdDicts.jl/branch/main/graph/badge.svg?token=IeRxFxQwG8&flag=WeakKeyIdDicts)](https://app.codecov.io/gh/beacon-biosignals/WeakKeyIdDicts.jl/tree/main) -Implements a WeakKeyIdDict which constructs a hash table where the keys are weak -references to objects that may be garbage collected even when referenced in a hash table. +Implements one public type, `WeakKeyIdDict`. It constructs a hash table where the keys are weak references to objects that may be garbage collected even when referenced in a hash table. Like [`WeakKeyDict`](https://docs.julialang.org/en/v1/base/collections/#Base.WeakKeyDict) it only supports keys that are mutable objects (all objects satisfying `ismutable(obj) == true`, such as Strings, Arrays and objects defined with `mutable struct`). Like [`IdDict`](https://docs.julialang.org/en/v1/base/collections/#Base.IdDict) the keys are hashed by `objectid`. -It defines one type, `WeakKeyIdDict`, that follows the same API as `Dict`. +A dictionary with weak keys is useful when we wish to store information about an object that survives only for the life-time of that object, usually to avoid memory leaks. For instance, if we wish to cache some hard-to-compute value associated with the keys of the dictionary. ```julia _tmp_key = [1] @@ -21,3 +20,5 @@ GC.gc(true) @show length(wkd) # 1 ``` + +Avoid assuming a key exists in a `WeakKeyIdDict`, especially when allocation occurs. Keys can be removed any time garbage collection occurs. Favor the methods `get!` and `get` over `getindex`.