Module Stdlib.Weak
Contents
Instructions: Use this module in your project
In the IDE (CLion, Visual Studio Code, Xcode, etc.) you use for your DkSDK project:
Add the following to your project's
dependencies/CMakeLists.txt:DkSDKProject_DeclareAvailable(ocaml CONSTRAINT "= 4.14.0" FINDLIBS str unix runtime_events threads dynlink) DkSDKProject_MakeAvailable(ocaml)Add the
Findlib::ocamllibrary to any desired targets insrc/*/CMakeLists.txt:target_link_libraries(YourPackage_YourLibraryName # ... existing libraries, if any ... Findlib::ocaml)Click your IDE's
Buildbutton
Not using DkSDK?
FIRST, do one or all of the following:
Run:
opam install ocaml.4.14.0Edit your
dune-projectand add:(package (name YourExistingPackage) (depends ; ... existing dependenices ... (ocaml (>= 4.14.0))))Then run:
dune build *.opam # if this fails, run: dune buildEdit your
<package>.opamfile and add:depends: [ # ... existing dependencies ... "ocaml" {>= "4.14.0"} ]Then run:
opam install . --deps-only
FINALLY, add the library to any desired (library)and/or (executable) targets in your **/dune files:
(library
(name YourLibrary)
; ... existing library options ...
(libraries
; ... existing libraries ...
))
(executable
(name YourExecutable)
; ... existing executable options ...
(libraries
; ... existing libraries ...
))Low-level functions
type``!'a t
The type of arrays of weak pointers (weak arrays). A weak pointer is a value that the garbage collector may erase whenever the value is not used any more (through normal pointers) by the program. Note that finalisation functions are run before the weak pointers are erased, because the finalisation functions can make values alive again (before 4.03 the finalisation functions were run after).
A weak pointer is said to be full if it points to a value, empty if the value was erased by the GC.
Notes:
- Integers are not allocated and cannot be stored in weak arrays.
- Weak arrays cannot be marshaled using
Stdlib.output_valuenor the functions of theMarshalmodule.
valcreate : ``int->'at
Weak.create n returns a new weak array of length n. All the pointers
are initially empty.
-
raises Invalid_argument
if
nis not comprised between zero andObj.Ephemeron.max_ephe_length(limits included).
vallength :'at->int
Weak.length ar returns the length (number of elements) of ar.
valset :'at->``int->'aoption``->unit
Weak.set ar n (Some el) sets the nth cell of ar to be a (full)
pointer to el; Weak.set ar n None sets the nth cell of ar to
empty.
-
raises Invalid_argument
if
nis not in the range 0 toWeak.lengtha - 1.
valget :'at->``int->'aoption
Weak.get ar n returns None if the nth cell of ar is empty,
Some x (where x is the value) if it is full.
-
raises Invalid_argument
if
nis not in the range 0 toWeak.lengtha - 1.
valget_copy :'at->``int->'aoption
Weak.get_copy ar n returns None if the nth cell of ar is empty,
Some x (where x is a (shallow) copy of the value) if it is full. In
addition to pitfalls with mutable values, the interesting difference
with get is that get_copy does not prevent the incremental GC from
erasing the value in its current cycle (get may delay the erasure to
the next GC cycle).
-
raises Invalid_argument
if
nis not in the range 0 toWeak.lengtha - 1.If the element is a custom block it is not copied.
valcheck :'at->``int->bool
Weak.check ar n returns true if the nth cell of ar is full,
false if it is empty. Note that even if Weak.check ar n returns
true, a subsequent Weak.get ar n can return None.
valfill :'at->``int->``int->'aoption``->unit
Weak.fill ar ofs len el sets to el all pointers of ar from ofs
to ofs + len - 1.
-
raises Invalid_argument
if
ofsandlendo not designate a valid subarray ofa.
Weak.blit ar1 off1 ar2 off2 len copies len weak pointers from ar1
(starting at off1) to ar2 (starting at off2). It works correctly
even if ar1 and ar2 are the same.
-
raises Invalid_argument
if
off1andlendo not designate a valid subarray ofar1, or ifoff2andlendo not designate a valid subarray ofar2.
Weak hash sets
A weak hash set is a hashed set of values. Each value may magically
disappear from the set when it is not used by the rest of the program
any more. This is normally used to share data structures without
inducing memory leaks. Weak hash sets are defined on values from a
Hashtbl.HashedType
module; the equal relation and hash function are taken from that
module. We will say that v is an instance of x if equal x v is
true.
The equal relation must be able to work on a shallow copy of the
values and give the same result as with the values themselves.
Functor building an implementation of the weak hash set structure.
H.equal can't be the physical equality, since only shallow copies of
the elements in the set are given to it.
