On Tuesday, 2 January 2018 at 20:07:11 UTC, jmh530 wrote:
> What's the monitor do? I see that in the ABI documentation, but it doesn't really explain it...

A monitor queues/schedules processes that are calling methods of an object so that only one process is executing methods on a single object at any given point in time.

https://en.wikipedia.org/wiki/Monitor_(synchronization)

On Tuesday, 2 January 2018 at 17:16:54 UTC, Steven Schveighoffer wrote:
>
> I would actually recommend ddocing each of the overloads of destroy individually instead of lumping them together, identifying what happens with each one.

I first wrote an extra one for just structs, but then decided to keep it all combined for all, to try and make things easier to remember. But maybe the differences are too large indeed.

-Johan

On Tuesday, 2 January 2018 at 17:16:54 UTC, Steven Schveighoffer wrote:
> On 1/2/18 8:58 AM, Johan Engelen wrote:
>> Hi all,
>> 
>> Link: https://dlang.org/library/object/destroy.html

Much obliged to anyone doing the effort of fixing and improving the doc.

I think Steven made a nice start. I added some comments below.

> It does something different depending on the type:
>
> Objects: calls rt_finalize on the object, which calls the dtor, deletes the monitor, rewrites the init value to the object, and THEN zeroes the vtable ptr. This last step makes it inoperable for anyone still holding a pointer to the object. This is why I think the docs are written the way they are.

rt_finalize is an implementation detail and shouldn't be in the docs here.
Important to mention the re-init _and_ the obj still being in invalid state (vtable is implementation detail and may be left out).

> Interfaces: If this is a D object, casts to Object and calls destroy on it.
>
> Structs: calls the dtor (if it exists), destroys recursively all the data members of the struct, and then initializes the data to it's init state.
>
> Everything else: overwrites with the init data. More explicitly, destroying a pointer simply sets it to null, and does not destroy what it points at.

I find "does not destroy what it points at" important to mention. (perhaps even with an explicit "you have to dereference the pointer to destroy what it points at").

Thanks,
Cheers,
  Johan