Note: I will be squashing these commits into a more coherent set and order.

Thanks for making the PR @NickBarnes. I've marked this as a draft until it is ready for review.

As a start, it would be helpful to get answers to a few questions:

1. Will all the features supported on 4.14 for sequential programs be supported here?
2. Are there breaking changes to the API for sequential programs?
3. Will statmemprof work on programs that spawn domains?
4. If multiple domains are supported, are the profiles maintained separately for each domain or is it aggregated globally?
5. Is the API safe to be used from multiple domains?

Single-domain semantic changes

I have made a few small semantic changes for single-domain programs. I have discussed these with the relevant developers at Jane Street, who are the main users of statmemprof in OCaml 4 (via their memtrace tool).

• Gc.Memprof.start now returns a value of type Gc.Memprof.t: the "profile". This has enabled me to add a new Gc.Memprof.discard function, and may also be useful for future additions to the Gc.Memprof API.
• Gc.Memprof.stop used to stop all callbacks. Now it stops sampling new allocations, but callbacks will continue to run for already-sampled allocations until the new function Gc.Memprof.discard is called. This allows profiling of all allocation which took place during some period of interest, continuing during the subsequent execution of a program (for example, one can discover when objects are GCed, without having to continue allocation sampling).
• Gc.Memprof.discard: t -> unit has been added. This stops all callbacks for the identified profile.
• The value Gc.Memprof.Marshal (part of type allocation_source = Normal | Marshal | Custom) is no longer used for unmarshalling. Unmarshalling in OCaml 5.0 uses the same allocation calls as other runtime allocations, so unmarshalling allocations will be Normal.

Multi-domain and multi-thread semantics

• Each thread (systhread) runs its own allocation callbacks, unless the thread exits before calling the callback (in which case statmemprof will attempt to run them in another thread of the same domain). (this is the same as OCaml 4).
• Profiling is per-domain. Gc.Memprof.start starts a profile for (all systhreads in) the current domain. Separate domains can run separate profiles wholly independently (they don't have to share callbacks, sampling frequency, or callstack depth).
• If a domain is spawned when the parent domain is sampling allocations, the child domain also samples allocations (with the same "profile").
• Gc.Memprof.stop stops sampling for all domains using the current domain's profile.
• Each domain runs all its own callbacks, unless it terminates (in which case statmemprof will attempt to run them in another domain).
• This is all intended to be thread-safe and multi-domain safe. There are currently bugs!

Thanks for the answers Nick.

I am restructuring this as a number of much smaller PRs which can be reviewed more-or-less independently. #12381 is the first.

I've introduced the label statmemprof to manage of the different PRs better: https://github.com/ocaml/ocaml/pulls?q=is%3Apr+is%3Aopen+label%3Astatmemprof.

I have discussed these with the relevant developers at Jane Street, who are the main users of statmemprof in OCaml 4 (via their memtrace tool).

Just a quick note: there are statmemprof users outside Jane Street, and going forward it would be nice to give them the opportunity the participate to API evolution discussion. For example some discussions could happen using an issue on github/ocaml or thee new "Discussion", or on Discuss, whatever.

The value Gc.Memprof.Marshal (part of type allocation_source = Normal | Marshal | Custom) is no longer used for unmarshalling. Unmarshalling in OCaml 5.0 uses the same allocation calls as other runtime allocations, so unmarshalling allocations will be Normal.

How useful is this distinction? I suspect that it is not hard to make it work in OCaml 5.0.

Closing since #12923 (which was much better) was merged.