Module Weak_hashtbl
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.bar
At 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 -> Ppx_sexp_conv_lib.Sexp.t) -> ('b -> Ppx_sexp_conv_lib.Sexp.t) -> ('a, 'b) t -> Ppx_sexp_conv_lib.Sexp.t
val create : ?growth_allowed:bool -> ?size:int -> (module Weak_hashtbl__.Import.Hashtbl.Key_plain with type t = 'a) -> ('a, 'b) t
growth_allowed
andsize
are both optionally passed on to the underlying call toHashtbl.create
.
module Using_hashable : sig ... end
val mem : ('a, _) t -> 'a -> bool
val find : ('a, 'b) t -> 'a -> 'b Weak_hashtbl__.Import.Heap_block.t option
val find_or_add : ('a, 'b) t -> 'a -> default:(unit -> 'b Weak_hashtbl__.Import.Heap_block.t) -> 'b Weak_hashtbl__.Import.Heap_block.t
val remove : ('a, 'b) t -> 'a -> unit
val add_exn : ('a, 'b) t -> key:'a -> data:'b Weak_hashtbl__.Import.Heap_block.t -> unit
val replace : ('a, 'b) t -> key:'a -> data:'b Weak_hashtbl__.Import.Heap_block.t -> unit
val key_is_using_space : ('a, _) t -> 'a -> bool
key_is_using_space t key
returnstrue
ifkey
is using some space int
.mem t key
implieskey_is_using_space t key
, but it is also possible that thatkey_is_using_space t key && not (mem t key)
.
val reclaim_space_for_keys_with_unused_data : (_, _) t -> unit
reclaim_space_for_keys_with_unused_data t
reclaims space for all keys int
whose data has been detected (by a finalizer) to be unused. Onlykey
s such thatkey_is_using_space t key && not (mem t key)
will be reclaimed.
val set_run_when_unused_data : (_, _) t -> thread_safe_f:(unit -> unit) -> unit
set_run_when_unused_data t ~thread_safe_f
callsthread_safe_f
in the finalizer attached to eachdata
int
, after ensuring the entry being finalized will be handled in the next call toreclaim_space_for_keys_with_unused_data
. This can be used to arrange to callreclaim_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 anyWeak_hashtbl
functions.