Hi all,

Link: https://dlang.org/library/object/destroy.html

The documentation says "Destroys the given object and puts it in an invalid state. " However, this is not (strictly) true. What destroy() does is overwrite the object with T.init (or zeros), and we should explicitly mention that. Also, the documentation states "that it [the object destroyed] no longer references any other objects.", which is wrong as this code shows:

```
__gshared int global;
struct S {
    int* pint = &global;
}
void main() {
    S s;
    int i;
    s.pint = &i;
    assert(s.pint != &global);
    destroy(s);
    assert(s.pint != &global); // fails
}
```
https://run.dlang.io/is/SFbxNm

How about:
"Destroys the given object `obj` and puts `obj` in its `T.init` state. This function used to destroy an object such that any cleanup by the destructor or finalizer is done, and such that `obj` no longer references any other objects (unless `T.init` references other objects). This function does not initiate a GC cycle nor free any GC memory."

regards,
  Johan

On Tuesday, 2 January 2018 at 13:58:49 UTC, Johan Engelen wrote:
> Hi all,
>
> Link: https://dlang.org/library/object/destroy.html
>
> The documentation says "Destroys the given object and puts it in an invalid state. " However, this is not (strictly) true. What destroy() does is overwrite the object with T.init (or zeros), and we should explicitly mention that. Also, the documentation states "that it [the object destroyed] no longer references any other objects.", which is wrong as this code shows:
>
> ```
> __gshared int global;
> struct S {
>     int* pint = &global;
> }
> void main() {
>     S s;
>     int i;
>     s.pint = &i;
>     assert(s.pint != &global);
>     destroy(s);
>     assert(s.pint != &global); // fails
> }
> ```
> https://run.dlang.io/is/SFbxNm
>
> How about:
> "Destroys the given object `obj` and puts `obj` in its `T.init` state. This function used to destroy an object such that any cleanup by the destructor or finalizer is done, and such that `obj` no longer references any other objects (unless `T.init` references other objects). This function does not initiate a GC cycle nor free any GC memory."
>
> regards,
>   Johan

Why not zerofy the object ?

On Tuesday, 2 January 2018 at 14:22:06 UTC, Temtaime wrote:
>
> Why not zerofy the object ?

Please keep the discussion on the topic of documentation, thanks.

-Johan

On Tuesday, 2 January 2018 at 14:39:52 UTC, Johan Engelen wrote:
> On Tuesday, 2 January 2018 at 14:22:06 UTC, Temtaime wrote:
>>
>> Why not zerofy the object ?
>
> Please keep the discussion on the topic of documentation, thanks.
>
> -Johan

Documentation does not correspond with the actual behavior, so fill a PR and that's all.
Then why even this topic is created ?

On Tuesday, 2 January 2018 at 13:58:49 UTC, Johan Engelen wrote:
> Hi all,
>
> Link: https://dlang.org/library/object/destroy.html
>
> [...]
Destroy calls the finalized function. (Which last time I check it's still a c function)

On Tuesday, 2 January 2018 at 13:58:49 UTC, Johan Engelen wrote:

> How about:
> "Destroys the given object `obj` and puts `obj` in its `T.init` state. This function used to destroy an object such that any cleanup by the destructor or finalizer is done, and such that `obj` no longer references any other objects (unless `T.init` references other objects). This function does not initiate a GC cycle nor free any GC memory."

I think you meant "This function *is* used..."

I suggest the following:

Calls `obj`'s destructor and sets `obj` to its default initial state, `T.init`.  This function does not initiate a GC cycle nor does it free any GC memory.

Mike

On Tuesday, 2 January 2018 at 15:13:46 UTC, Mike Franklin wrote:
> [..]
>
> I suggest the following:
>
> Calls `obj`'s destructor and sets `obj` to its default initial state, `T.init`.  This function does not initiate a GC cycle nor does it free any GC memory.
>
> Mike

+1

On 1/2/18 8:58 AM, Johan Engelen wrote:
> Hi all,
> 
> Link: https://dlang.org/library/object/destroy.html
> 
> The documentation says "Destroys the given object and puts it in an invalid state. " However, this is not (strictly) true. What destroy() does is overwrite the object with T.init (or zeros), and we should explicitly mention that. Also, the documentation states "that it [the object destroyed] no longer references any other objects.", which is wrong as this code shows:

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.

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 would actually recommend ddocing each of the overloads of destroy individually instead of lumping them together, identifying what happens with each one.

-Steve

On Tuesday, 2 January 2018 at 17:16:54 UTC, Steven Schveighoffer wrote:
>
> 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.


What's the monitor do? I see that in the ABI documentation, but it doesn't really explain it...

On 1/2/18 3:07 PM, jmh530 wrote:
> On Tuesday, 2 January 2018 at 17:16:54 UTC, Steven Schveighoffer wrote:
>>
>> 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.
> 
> 
> What's the monitor do? I see that in the ABI documentation, but it doesn't really explain it...

The monitor is used to lock any object for synchronization.

It's allocated on demand.

https://dlang.org/spec/class.html#synchronized-classes

-Steve