DIP74

From D Wiki
Revision as of 16:23, 26 February 2015 by AndreiAlexandrescu (talk | contribs)
Jump to: navigation, search
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:

  1. All parameters are memcpy'd
  2. Postblit call for x
  3. y.AddRef()
  4. Postblit call for z
  5. Function is entered
  6. Destructor call for z
  7. y.Release()
  8. Destructor call for x
  9. Function returns
  • Functions that return a reference counted reference call AddRef against the returned reference.
  • The compiler considers that Release is the inverse of AddRef, and therefore is at liberty to elide pairs of calls to AddRef/Release. Example:
Widget fun() {
    auto a = new Widget;
    auto b = a;
    return b;
}

Applying the rules defined above would have fun's lowering insert two calls to AddRef (one for creating b, the other for the returned value) and two calls to Release (when a and b go out of scope). However, all these calls may be elided.

  • 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.