Add Profiler API : GetObjectReferences

[mjsabby]

The Profiler API today has ICorProfilerCallback::ObjectReferences which is called after a GC is completed. This is called for remaining object in the heap.

For large heaps and/or heaps with moderate survival rate this can be prohibitively expensive to enable in a production environment.

In conjuction with https://github.com/dotnet/coreclr/issues/24132, this API can be used to selectively traverse object graphs. In fact, with this API you could implement the aforementioned expensive callback that already exists in the profiling API. So this customization is a welcome addition to the Profiler API.

The signature would be:

GetObjectReferences(ObjectID objectId, ULONG32 cNumReferences, ULONG32 *pcNumReferences, ObjectID references[])

Passing 0 for cNumReferences will fill do a traversal for this object and fill up pcNumReferences. A subsequent call with the cNumReferences parameter set to the value returned in the first call (pcNumReferences) will expect an appropriately allocated array of ObjectIDs to fill the data in.

A point of discussion could be if field offsets should be included. I'm of the opinion they are superflous for most object graph traversals.

[mjsabby]

cc @Maoni0 @noahfalk

[noahfalk]

@davmason

A point of discussion could be if field offsets should be included. I'm of the opinion they are superflous for most object graph traversals.

If you don't include them it is very hard to determine which fields hold which references. Check out issue #9685 for a good example of a serious profiling tool that cares about this. If there is a significant complexity it adds to the design or usage we should discuss, but on first impression it feels like a pretty low cost addition that solves a real problem with the existing API.

[mjsabby]

I don't have a problem in adding offsets, it's just that the existing code just worked and was a good way to gauge if there are other issues or concerns the team has. Now I'll have to write a custom go_through_object handler, but that's not a lot of work.

[noahfalk]

I'm re-opening this issue until docs are in place (I think GitHub auto-closes when you merge the PR)

[davmason]

@mjsabby have you worked on docs at all?

[mikelle-rogers]

Already documented.