Difference between revisions of "DIP74"

From D Wiki
Jump to: navigation, search
Line 10: Line 10:
 
|-
 
|-
 
|Status:
 
|Status:
|Concept
+
|Draft
 
|-
 
|-
 
|Created:
 
|Created:
Line 35: Line 35:
 
<syntaxhighlight lang=D>
 
<syntaxhighlight lang=D>
 
class Widget {
 
class Widget {
     ulong AddRef();
+
     T1 AddRef();
     ulong Release();
+
     T2 Release();
 
     ...
 
     ...
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The methods may or may not be <tt>final</tt> or inherited. Any attributes are allowed on these methods. They must be public. If these two methods are accessible, the compiler categorizes this <tt>class</tt> type as a reference counted <tt>class</tt> and treats it as follows:
+
<tt>T1</tt> and <tt>T2</tt> may be any types (usually <tt>void</tt> or an integral type). The methods may or may not be <tt>final</tt> or inherited. Any attributes are allowed on these methods. They must be public. UFCS-expanded calls are not acceptable. If these two methods exist and are accessible, the compiler categorizes this <tt>class</tt> or <tt>interface</tt> type as a ''reference counted reference'' and treats it as follows:
  
* Whenever a new reference to an object is created, compiler inserts an implicit call to <tt>AddRef</tt>. Call is inserted only if the reference is not <tt>null</tt>. There is no call inserted for the first reference created via a constructor.
+
* Whenever a new reference to an object is created (e.g. <tt>auto a = b;</tt>, compiler inserts a call to <tt>AddRef</tt> in the generated code. Call is inserted only if the reference is not <tt>null</tt>. The lowering of <tt>auto a = b;</tt> is conceptually <tt>if (b) b.AddRef(); auto a = b;</tt>
* Whenever a reference to an object is assigned (e.g. <tt>a = b</tt>), first <tt>b.AddRef</tt> is called and then <tt>a.Release()</tt> is called, followed by the reference assignment itself. Calls are only made if the respective objects are not <tt>null</tt>.
+
* There is no call inserted for the first reference created via a constructor (i.e. it is assumed the constructor already puts the object in the appropriate state). For example the lowering of <tt>auto a = new Widget;</tt> does not insert a call to <tt>AddRef</tt>.
* Whenever a reference to an object goes out of scope, compiler inserts an implicit call to <tt>Release</tt>. Call is inserted only if the reference is not <tt>null</tt>.
+
* Whenever a reference to an object is assigned (e.g. <tt>a = b</tt>), first <tt>b.AddRef</tt> is called and then <tt>a.Release()</tt> is called, followed by the reference assignment itself. Calls are only made if the respective objects are not <tt>null</tt>. So the lowering of e.g. <tt>a = b;</tt> is <tt>if (b) b.AddRef(); if (a) a.Release(); a = b;</tt>
* Implicit conversion to supertypes (<tt>class</tt> or <tt>interface</tt>) is allowed ONLY if the supertype also is a reference counted type. It follows that reference counted types cannot be converted to <tt>Object</tt> (unless <tt>Object</tt> itself defines the two methods).
+
* Whenever a reference to an object goes out of scope, the compiler inserts an implicit call to <tt>Release</tt>. Call is inserted only if the reference is not <tt>null</tt>.
 +
* The pass-by-value protocol for reference counted references is as follows: the caller calls <tt>AddRef</tt> and the callee calls </tt>Release</tt>. These calls are sequenced and handled the same as copy constructor calls and destructor calls, respectively, for <tt>struct</tt> objects. Example:
 +
 
 +
<syntaxhighlight lang=D>
 +
struct A {
 +
    this(this);
 +
    ~this();
 +
}
 +
void fun(A x, Widget y, A z) {
 +
}
 +
</syntaxhighlight>
 +
 
 +
In the code above, calling fun entails the sequence:
 +
 
 +
** All parameters are <tt>memcpy</tt>'d
 +
** Postblit call for <tt>x</tt>
 +
** <tt>y.AddRef()</tt>
 +
** Postblit call for <tt>z</tt>
 +
** Function is entered
 +
** Destructor call for <tt>z</tt>
 +
** <tt>y.Release()</tt>
 +
** Destructor call for <tt>x</tt>
 +
** Function returns
 +
 +
* Implicit conversion to supertypes (<tt>class</tt> or <tt>interface</tt>) is allowed ONLY if the supertype is also a reference counted type. It follows that reference counted types cannot be converted to <tt>Object</tt> (unless <tt>Object</tt> itself defines the two methods).
 
* Typechecking methods of reference counted types is done the same as for <tt>struct</tt>s. This is important because it limits what reference counted types. Consider:
 
* Typechecking methods of reference counted types is done the same as for <tt>struct</tt>s. This is important because it limits what reference counted types. Consider:
  

Revision as of 16:07, 26 February 2015

Title: Safe Reference Counted Class Objects
DIP: 74
Version: 1
Status: Draft
Created: 2015-02-23
Last Modified: 2015-02-26
Author: Walter Bright and Andrei Alexandrescu

Abstract

This DIP proposes @safe reference counted class objects for D (including exceptions).

Description

DIP25 allows defining struct types that own data and expose references to it, @safely, whilst controlling lifetime of that data. This proposal allows defining class objects that are safe yet use deterministic destruction for themselves and resources they own.

The compiler detects automatically and treats specially all classes and interfaces that define the following two methods:

class Widget {
    T1 AddRef();
    T2 Release();
    ...
}

T1 and T2 may be any types (usually void or an integral type). The methods may or may not be final or inherited. Any attributes are allowed on these methods. They must be public. UFCS-expanded calls are not acceptable. If these two methods exist and are accessible, the compiler categorizes this class or interface type as a reference counted reference and treats it as follows:

  • Whenever a new reference to an object is created (e.g. auto a = b;, compiler inserts a call to AddRef in the generated code. Call is inserted only if the reference is not null. The lowering of auto a = b; is conceptually if (b) b.AddRef(); auto a = b;
  • There is no call inserted for the first reference created via a constructor (i.e. it is assumed the constructor already puts the object in the appropriate state). For example the lowering of auto a = new Widget; does not insert a call to AddRef.
  • Whenever a reference to an object is assigned (e.g. a = b), first b.AddRef is called and then a.Release() is called, followed by the reference assignment itself. Calls are only made if the respective objects are not null. So the lowering of e.g. a = b; is if (b) b.AddRef(); if (a) a.Release(); a = b;
  • Whenever a reference to an object goes out of scope, the compiler inserts an implicit call to Release. Call is inserted only if the reference is not null.
  • The pass-by-value protocol for reference counted references is as follows: the caller calls AddRef and the callee calls Release. These calls are sequenced and handled the same as copy constructor calls and destructor calls, respectively, for struct objects. Example:
struct A {
    this(this);
    ~this();
}
void fun(A x, Widget y, A z) {
}

In the code above, calling fun entails the sequence:

    • All parameters are memcpy'd
    • Postblit call for x
    • y.AddRef()
    • Postblit call for z
    • Function is entered
    • Destructor call for z
    • y.Release()
    • Destructor call for x
    • Function returns
  • Implicit conversion to supertypes (class or interface) is allowed ONLY if the supertype is also a reference counted type. It follows that reference counted types cannot be converted to Object (unless Object itself defines the two methods).
  • Typechecking methods of reference counted types is done the same as for structs. This is important because it limits what reference counted types. Consider:
@safe class Widget1 {
    private int data;
    ref int getData() { return data; } // fine
    ...
}

@safe class Widget2 {
    private int data;
    ref int getData1() { return data; } // ERROR
    ref int getData2() return { return data; } // fine
    ulong AddRef();
    ulong Release();
    ...
}

This is because it is safe for a garbage collected object to escape references to its internal state. The same is not allowed for reference counted objects because they are expected to be deallocated in a deterministic manner (same as e.g. struct objects on the stack).

Defining a reference counted object with deallocation

TODO

class Widget {
   ulong AddRef();
   ulong Release();
   ...
}

Copyright

This document has been placed in the Public Domain.