package core_kernel
Install
Dune Dependency
Authors
Maintainers
Sources
sha256=fd2b8c6715794df7a810a62b226f53720f211cd344b4afc9fab0498796d6b466
doc/core_kernel.weak_hashtbl/Weak_hashtbl/index.html
Module Weak_hashtblSource
A hashtable that keeps a weak pointer to each key's data and uses a finalizer to detect when the data is no longer referenced (by any non-weak pointers).
Once a key's data is finalized, the table will effectively behave as if the key is not in the table, e.g., find will return None. However, one must call reclaim_space_for_keys_with_unused_data to actually reclaim the space used by the table for such keys.
Unlike (OCaml's) Weak.Make, which also describes itself as a "weak hashtable," Weak_hashtbl gives a dictionary-style structure. In fact, OCaml's Weak.Make may better be described as a weak set.
There's a tricky type of bug one can write with this module, e.g.:
type t =
{ foo : string
; bar : float Incr.t
}
let tbl = Weak_hashtbl.create ()
let x1 =
let t = Weak_hashtbl.find_or_add tbl key ~default:(fun () ->
(... some function that computes a t...))
in
t.barAt this point, the data associated with key is unreachable (since all we did with it was project out field bar), so it may disappear from the table at any time.
val sexp_of_t :
('a -> Sexplib0.Sexp.t) ->
('b -> Sexplib0.Sexp.t) ->
('a, 'b) t ->
Sexplib0.Sexp.tval create :
?growth_allowed:Base.bool ->
?size:Base.int ->
(module Base.Hashtbl.Key.S with type t = 'a) ->
('a, 'b) tgrowth_allowed and size are both optionally passed on to the underlying call to Hashtbl.create.
val find_or_add :
('a, 'b) t ->
'a ->
default:(Base.unit -> 'b Heap_block.t) ->
'b Heap_block.tkey_is_using_space t key returns true if key is using some space in t. mem t key implies key_is_using_space t key, but it is also possible that that key_is_using_space t key && not (mem t key).
reclaim_space_for_keys_with_unused_data t reclaims space for all keys in t whose data has been detected (by a finalizer) to be unused. Only keys such that key_is_using_space t key && not (mem t key) will be reclaimed.
val set_run_when_unused_data :
(_, _) t ->
thread_safe_f:(Base.unit -> Base.unit) ->
Base.unitset_run_when_unused_data t ~thread_safe_f calls thread_safe_f in the finalizer attached to each data in t, after ensuring the entry being finalized will be handled in the next call to reclaim_space_for_keys_with_unused_data. This can be used to arrange to call reclaim_space_for_keys_with_unused_data at a convenient time in the future. thread_safe_f must be thread safe -- it is not safe for it to call any Weak_hashtbl functions.