The GCHandle.Free page needs to say more

[daveyostcom]

I came here from the GCHandle.Free F# page.

The page should say more:

1. Even after GCHandle.Free() is called, the object itself can still be used by any code that possesses a reference to it.
2. A pinned handle is no longer pinned after GCHandle.Free(). (Or is it?)

All behavior wrt pinning should be explained somewhere (the GCHandleType page?) and referred to everywhere it is relevant. Contrasting the behavior of a pinned object vs system memory should also fully explained in the same place.

Other thoughts

If a GCHandle is still pinned after GCHandle.Free() then it seems reasonable that one should immediately free a pinned handle after pinning it. Also, it might be reasonable to do so in most other circumstances, and this should be discussed.

A GCHandle.IsPinned property would be good.

One is led to believe that the object will be pinned wherever it is at the moment, which could cause a fragmentation problem. Perhaps there should be another argument to Alloc that can be used to ask the collector to pack the object into the long-lived generation or to move it to system memory. This last would be especially good for an object that will never be freed. Moving to system memory would probably warrant additions for GCHandleType.SystemMemory and GCHandle.IsSystemMemory.

I couldn't figure out the best area label to add to this issue. If you have write-permissions please help me learn by adding exactly one area label.