Module Gc.Memprof
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 ...
))typeallocation_source`` =
|Normal
|Marshal
|Custom
typeallocation`` =private``{
n_samples : int;(* The number of samples in this block (>= 1).
*)
size : int;(* The size of the block, in words, excluding the header.
*)
source :allocation_source;(* The type of the allocation.
*)
callstack :Printexc.raw_backtrace;(* The callstack for the allocation.
*)
}
The type of metadata associated with allocations. This is the type of records passed to the callback triggered by the sampling of an allocation.
type``('minor, 'major) tracker`` = ``{
alloc_minor :allocation->'minoroption``;
alloc_major :allocation->'majoroption``;
promote :'minor->'majoroption``;
dealloc_minor :'minor->unit;
dealloc_major :'major->unit;}
A ('minor, 'major) tracker describes how memprof should track sampled
blocks over their lifetime, keeping a user-defined piece of metadata for
each of them: 'minor is the type of metadata to keep for minor blocks,
and 'major the type of metadata for major blocks.
When using threads, it is guaranteed that allocation callbacks are always run in the thread where the allocation takes place.
If an allocation-tracking or promotion-tracking function returns None,
memprof stops tracking the corresponding value.
valnull_tracker : ``('minor,'major)``tracker
Default callbacks simply return None or ()
valstart : ``sampling_rate:float->``?callstack_size:int->``('minor,'major)``tracker->unit
Start the sampling with the given parameters. Fails if sampling is already active.
The parameter sampling_rate is the sampling rate in samples per word
(including headers). Usually, with cheap callbacks, a rate of 1e-4 has
no visible effect on performance, and 1e-3 causes the program to run a
few percent slower
The parameter callstack_size is the length of the callstack recorded
at every sample. Its default is max_int.
The parameter tracker determines how to track sampled blocks over
their lifetime in the minor and major heap.
Sampling is temporarily disabled when calling a callback for the current thread. So they do not need to be re-entrant if the program is single-threaded. However, if threads are used, it is possible that a context switch occurs during a callback, in this case the callback functions must be re-entrant.
Note that the callback can be postponed slightly after the actual event. The callstack passed to the callback is always accurate, but the program state may have evolved.
valstop : ``unit->unit
Stop the sampling. Fails if sampling is not active.
This function does not allocate memory.
All the already tracked blocks are discarded. If there are pending postponed callbacks, they may be discarded.
Calling stop when a callback is running can lead to callbacks not
being called even though some events happened.
