DIP74

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 (including exceptions) and interfaces for D.

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 opAddRef();
    T2 opRelease();
    ...
}

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 object (RCO).

Rules

RCOs are handles as follows:

• Whenever a new reference to an object is created (e.g. auto a = b;, compiler inserts a call to opAddRef 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.opAddRef(); 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 opAddRef.

• Whenever a reference to an object is assigned (e.g. a = b), first b.opAddRef() is called and then a.opRelease() 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.opAddRef(); if (a) a.opRelease(); a = b;

• Whenever a reference to an object goes out of scope, the compiler inserts an implicit call to opRelease. Call is inserted only if the reference is not null.

• The pass-by-value protocol for RCOs is as follows: the caller calls opAddRef and the callee calls opRelease. 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.opAddRef()
4. Postblit call for z
5. Function is entered
6. Destructor call for z
7. y.opRelease()
8. Destructor call for x
9. Function returns

• Functions that return an RCO call opAddRef against the returned reference, EXCEPT if the returned reference is an rvalue or a local variable. Functions that return a local variable do not call opRelease against it.

• The compiler considers that opRelease is the inverse of opAddRef, and therefore is at liberty to elide pairs of calls to opAddRef/opRelease. Example:

Widget fun() {
    auto a = new Widget;
    auto b = a;
    return b;
}

Applying the rules defined above would have fun's lowering insert one call to opAddRef (for creating b) and one call to opRelease (when a goes out of scope). However, 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).

• Explicit casting to void* does not entail a call to opAddRef.

• 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 opAddRef();
    ulong opRelease();
    ...
}

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 non-copyable reference type

Using @disable this(this); is a known idiom for creating struct objects that can be created and moved but not copied. The same is achievable with RCOs by means of @disable opAddRef();

Defining a reference counted object with deallocation

Classic reference counting techniques can be used with opAddRef and opRelease.

class Widget {
    private uint _refs = 1;
    void opAddRef() {
        ++refs;
    }
    void opRelease() {
        if (refs > 1) {
            --refs;
        } else {
            this.destroy();
            GC.free(cast(void*) this);
        }
    }
   ...
}

Usually such approaches also use private constructors and object factory to ensure the same allocation method is used during creation and destruction of the object.

If the object only needs to free this (and no other owned resources), the typechecking ensured by the compiler is enough to verify safety (however, @trusted needs to be applied to the call that frees this).

Defining a type that owns resources

TODO

Copyright

This document has been placed in the Public Domain.