GCHandle.IsAllocated documentation appears to be incorrect

[PathogenDavid]

The GCHandle.IsAllocated remarks states the following:

Use this property when using Weak handles to determine if the GCHandle is still available. When the garbage collector collects the object, the Weak handle can still be resurrected in the finalizer. In that case, the handle is not allocated (it is lost when the garbage collector attempts to collect the object), even though the target object is valid.

The implementation of IsAllocated only checks whether its internal handle is null:

public bool IsAllocated => _handle != IntPtr.Zero;

(The .NET Framework implementation is basically identical.)

Unless there's some magic handling of GCHandle in the runtime, I believe the only time _handle is null (and IsAllocated is false) is if the handle was never initialized or the actual handle was freed with Free().

Weak handles to freed objects are still allocated, they just don't point to anything (Target returns null.)

Empirical tests seem to confirm all of this.

Is this documentation incorrect or am I missing something?

[msedi]

I agree with @PathogenDavid. I'm found the problem because I couldn't use a WeakReference<T>. So it would be nice to hear if the docs are incorreect or the behavior is wrong.

[reflectronic]

@jkotas Can you clarify the expected behavior?

[jkotas]

Yes, the documentation is completely wrong.

IsAllocated is false is if the handle was never initialized or the handle was freed with Free.

Would you like to submit a PR with doc update?