Proposal: Static analysis to simplify resource management

[dmitrykm]

Static analysis to simplify resource management

Download this proposal as html (styled with css, text wrapping works):

• html.zip

Download this proposal as a set of markdown files:

• StaticAnalysisToSimplifyResourceManagement.zip

Introduction

GC solves the problem of managing RAM occupied by purely managed objects, but is useless for managing other types of resources.

Most resources used by applications require deterministic disposal. C# solves this problem by introducing the IDisposable interface, but using this interface correctly is hard due to limited support from the language.

This proposal focuses on making manual deterministic resource management easier.

Destructible Types #161 in Roslyn repo and Destructible Types #121 in csharplang repo address the problem of deterministic resource management by introducing Destructible Types and prohibiting to copy their values, while reserving the move keyword for ownership transfer. Thus Destructible Types are introduced directly to represent linear types.

This proposal instead models linear transfer of ownership by putting all the necessary constraints into separate keywords. The keywords act in conjunction with ordinary variables and types, while the types themselves do not carry any ownership constraints.

This proposal is built around the IDisposable interface because C# currently does not support destructors. All reasoning and examples here rely on IDisposable. That is done so because IDisposable is already a part of .net and C#, and it is easier to understand code samples that use familiar
C# features.

Types with destructors bound to stack and called automatically by the compiler allow very concise, clear, exception-safe code as in C++ and without constructs like try-finally or using.

On the other hand, keywords introduced by the current proposal are compatible with existing types and annotate ownership semantics in every place and context.

If any of the proposals, Destructible Types #161 in Roslyn repo, Destructible Types #121 in csharplang repo , or the current one is implemented, that will dramatically improve developers' experience.

This proposal focuses on compiler enforced resource tracking that is statically provable to be correct.

C++ has destructors, yet it needed to introduce smart pointers. This proposal starts from reasoning about smart pointers and then shows that in most cases it is possible to abandon smart pointers in favor of built-in compiler support, and manage resources easier and with less errors than smart pointers allow.

This proposal extends Proposal: move #160 with one more keyword, more syntactic contexts and use cases for the keywords, more constraints and static analysis.

Problems:

1. The compiler does not require calling Dispose(...) on objects of disposable types and thus does not enforce resource disposal
2. It is easy to forget to call Dispose(...)
3. It is even easier to overlook that an object returned by a method is disposable and needs to be disposed of. This problem is especially acute when calling methods implemented by other developers
4. Sometimes objects implementing IDisposable are not assumed to be disposed of by client code. Instead, those objects are either managed by a library/framework/other sides or implement IDisposable because some framework requires doing so, not because they manage resources and really need disposal. But from the language's standpoint, it is impossible to distinguish such objects from objects that really require disposing.
5. By looking at method signatures and type declarations it is impossible to figure out whether a particular method argument or return value needs disposal or not, and what side is responsible for this. Only documentation clarifies this, though not always. In other words, programming interfaces are not enough self-documenting with respect to resource management, because they lack proper language constructs to solve this problem.
6. Lifetimes of some resources span multiple methods and cannot be scoped to a single method and using-statement. Instead, such resources need to be held in class fields or properties.
   The using-statement cannot be applied to such use cases, and so the language implicitly discourages them, despite their necessity.
7. Without specific support from the language, it is hard to implement resource management correctly when resources are held in class fields or properties. Such fields and properties are often decoupled from the context where the resources they hold are allocated and deallocated. Looking at a class field or property that holds a disposable resource gives zero knowledge about who created that
   resource, who owns it and who must or must not dispose of it.
8. Resources need to be passed as arguments and return values between multiple methods and classes.
   Such arguments are also taken out of the context where the resources they carry
   are allocated and deallocated. Tracking the "world lines" and lifetimes of resources whose use is scattered across multiple methods and classes quickly
   becomes hard. Needless to say, users of a resource can save their own references to the resource,
   resulting in multiple references to the same resource.
9. Resources often need to be passed
   through interfaces between separate components/subsystems developed by different teams at different times. Different teams adopt different resource management conventions. Currently conventions and documentation is the only aid in resource management, and it is highly fragile and unreliable without being enforced by the compiler.

This proposal addresses all of the above.

Exclusive ownership

Exclusive ownership is a well-known and time-proven resource management model. Each resource has exactly one owner. The owner is responsible for disposing of the owned resource. unique_ptr in C++ is a popular implementation of the model.

Here is simple interface to represent the model:

public interface IXOwnershipResourceView<out TResource> : IDisposable
		where TResource : class, IDisposable
{
    TResource Resource { get; }
    bool IsOwner { get; }
    IXOwnershipResourceView<TResource> Move();
    IXOwnershipResourceView<TResource> Lease();
}

Users of the resource see it through "resource views". Each user has its own resource view. The resource can have many users and many resource views, but only one of the users (and resource views) is the resource owner (IXOwnershipResourceView.IsOwner == true), while others are merely allowed to use the resource as non-owners.

When non-owners call IXOwnershipResourceView.Dispose(), their resource views do nothing, while calling IXOwnershipResourceView.Dispose() on the owning resource view disposes of the underlying resource.

The owner may decide to transfer the ownership to someone else. Calling IXOwnershipResourceView.Move() transfers the ownership from the original resource view to a newly instantiated one and returns the latter.

The owner may decide to allow other parties to use the resource without ownership transfer. Calling IXOwnershipResourceView.Lease() creates and returns a new non-owning resource view for such cases.

Owning resource views can move and lease underlying resources to other resource views, while non-owning resource views can only lease underlying resources to other resource views.

The first instance of IXOwnershipResourceView created for a resource instance ("root" resource view) automatically becomes the owner. The root resource view can either be created using a dedicated constructor in a class implementing IXOwnershipResourceView or using a dedicated extension method:

//ToRootResourceView(...) is an extension method for FileStream 
IXOwnershipResourceView<FileStream> fsView = fs.ToRootResourceView()

All other instances of IXOwnershipResourceView for the same instance of the resource should
be derived via IXOwnershipResourceView.Move() and IXOwnershipResourceView.Lease(), to simplify the implementation.

Resource view derivation paths are flexible and in most cases form trees, e.g:

Example of resource view derivation

However, the absence of loops is not a requirement and paths like token ring are allowed.

Optimizing IXOwnershipResourceView

IXOwnershipResourceView as defined above does not differentiate owning and non-owning resource views at compile time.

Such flexibility is sometimes needed. If there are two parties, producer and consumer, producer can sometimes send products along with their ownership to consumer, while just lending products to consumer in other cases:

IXOwnershipResourceView<Product> Produce()
{
//...
}

void Consume()
{
    var p = new Producer();
    using(var productView = p.Produce())
    {
        //we do not know whether we own the
        //product here

        useProduct(productView);
    }//disposes of the product if we've owned it
}

However, we often know at compile time who is the resource owner in a particular method or class, because the program was designed accordingly. For such cases it would make sense to split IXOwnershipResourceView into two interfaces specific to owners and non-owners:

public interface IXOwningResourceView<out TResource> : IDisposable
		where TResource : class, IDisposable
{
    TResource Resource { get; }
    
    //move creates other owning resource views 
    IXOwningResourceView<TResource> Move();

    //lease creates other non-owning resource views 
    IXNonOwningResourceView<TResource> Lease();
}

public interface IXNonOwningResourceView<out TResource> 
		where TResource : class, IDisposable
{
    TResource Resource { get; }
    IXNonOwningResourceView<TResource> Lease();
}

The next optimization step is notice that IXOwningResourceView and IXNonOwningResourceView are not needed at all. They are merely resource holders and serve as markers that a particular resource is owned or not owned by some method argument, local variable, class field or property. IXOwningResourceView and IXNonOwningResourceView statically declare possible
topologies of resource view derivation. We remove IXOwningResourceView and IXNonOwningResourceView as it is sufficient to use the move and lease annotations to describe the
same topology to the compiler, without loosing any useful information.

Moving assignments

A moving assignment transfers a value (resource) and its ownership from the assignment source to the
assignment destination:

dst = move src;

//src no longer owns its value, 
//as the ownership has been moved to 
//dst

As soon as the ownership is transferred to dst, dst can do anything with the resource, including instantly disposing of it. This means that right after the moving assignment, src can no longer use or reference the resource. Moving assignment acts as an unidirectionally opaque wall where src is not allowed to observe what happens to the resource and how it is used after the moving assignment.

In some cases move-assignment sources can be referenced in code after being moved. The compiler resets the source's previous value by assigning default(TSrc) to the source in such cases:

dst = move src;

src = default(TSrc);//<--compiler-generated, 
//where TSrc is the type of src

//src no longer owns its value, 
//but can be referenced somewhere else
//in code 

Move-assignment sources whose moved values can be observed are ("observable moved sources"):

• Class fields
• Class properties
• Local variables and method parameters
  managed by using-blocks
• move-ref arguments of methods.

In other cases the compiler statically enforces that no-longer-valid values of moved assignment sources cannot be observed anywhere in code. In such cases every moved source is marked as uninitialized right after being moved. Trying to read such a source generates a compilation error. However, it is not prohibited to reinitialize the source with another value in order to reuse it.

Move-assignment sources whose moved values cannot be observed are ("unobservable moved sources"):

• Local variables and method parameters not managed by using-blocks

move and IDisposable

When move is used with types implementing IDisposable, the compiler performs additional analysis to prevent resource leaks.

Any owner of a disposable resource marked with move should either dispose of the resource directly or transfer this responsibility to another owner with the help of move.

Proposal core

The proposal consists of introducing:

• Two new keywords, move and lease
• New compiler warnings and errors to validate the paths of resource view derivation and assist in using classes implementing IDisposable
• Minor code generation to support move

The move and lease keywords can appear in different contexts.

move and lease as variable declaration specifiers

move in declarations of local variables, method parameters, class fields, class properties designates that the declared variable, method parameter, class field or property owns its value, while lease designates that the declared variable, method parameter, class field or property uses its value but does not own it:

lease int a = 1; //a does not own its value
move int b = 1;  //b owns its value
int c = 1;//nothing is known about ownership 

Declarations with neither move nor lease do not convey meaning related to ownership.

move and lease as modifiers of the assigment operator

move and lease appearing right after the assignment operator modify the assignment semantics accordingly.

Lease-assignment means that the source variable leases its value to the destination variable. The destination is then allowed to use the value while not owning it:

lease int dst = lease src; //lease-assignment

//dst can use its value, 
//but does not own it

Lease-assignment does not involve any run time changes and acts at run time exactly as
the ordinary assignment specific to the types of the source and destination. All the changes are used only for additional static analysis.

Move-assignment means that the source variable moves its value to the destination variable.
The destination becomes the new owner of the value, while the source no longer owns the value:

move int dst = move src;  //move-assignment

//src no longer owns its value 
//and cannot use it

//dst owns its value and can do 
//everything with it

At run time moving assignment looks like the ordinary assignment specific to the types of the source and destination, followed by assigning default(TSourceType) to the source when that is necessary.
Other sections detail this.

Passing arguments by move and lease into methods is semantically equivalent to move- and lease-assignments, just differs syntactically:

void MethodA(move int dst)
{ 
}

void UseA()
{
    //call MethodA and move-assign 
    //the value of src to dst
    MethodA(move src);
    
    //this is semantically equivalent to 
    //move int dst = move src;
    //where dst is the parameter of MethodA
}

More details about methods:
MethodParametersAndReturns

move and lease are available for all types

It is easy to reason about move and lease in terms of resources, especially in the context of managing IDisposable resources. However, thanks to their highly abstract nature, it is useful to allow these keywords for all types. One example immediately follows.

Example

Consider a multithreaded GUI application. We need to process all windows. Some windows are created
on threads other than the main UI thread. We can retrieve the collection of currently open windows, but this collection is constantly changing. We lock the collection for a short time and make its snapshot and further work only with that snapshot. The windows variable only exists to be passed into LockedClone(...). Accessing windows inside ProcessWindows(...) after calling LockedClone(...) is an error by design. move states this explicitly:

void ProcessWindows()
{    
    var windows = /* switch to the main UI 
    thread and retrieve the reference 
    to the windows collection*/

    if (windows == null || windows.Count == 0)
        return;

    Window[] windowsSnapshot = LockedClone(move windows);

    //compilation error CS0165:
    //Use of unassigned local variable 'windows'
    var main = windows[0];

    //
    //time consuming processing of windowsSnapshot here
    //
}

//WindowCollection does not implement IDisposable 
static Window[] LockedClone(move WindowCollection src)
{
    Window[] dst;
    Debug.Assert(src.SyncRoot != null, "src.SyncRoot != null");
    lock (src.SyncRoot)
    {
        dst = new Window[src.Count];
        src.CopyTo(dst, 0);
    }
    return dst;
}

The same can be achieved using additional {}-blocks, but they introduce indentation and interfere with the scopes of other local variables.

Assignment rules

Sources and destinations of assignments are local variables, method parameters and returns, class fields and properties.

If a source is not marked with move or lease at its declaration site explicitly and does not receive move or lease implicitly as a part of type inference, let us call such a source "unmarked". The two other possible states are "marked with lease" and "marked with move", no matter explicitly or implicitly.

In addition, destinations can be declared using var. var-declarations cannot specify move or lease but can receive them from type inference.

Assignment can be:

• ordinary assignment: dst = src;
• lease-assignment: dst = lease src;
• move-assignment: dst = move src;

Source: {Unmarked, Lease, Move}

Assignment: {Unmarked, Lease, Move}

Destination: {Unmarked, Lease, Move, Var}

The Cartesian product [Source] x [Assignment] x [Destination] consists of 36 cases.

There is one exception to these 36 cases: move and lease declared in method signatures are required to be exactly "mirrored" at all call sites, see "Method parameters and return values". This exception applies to all method call sites and has a higher priority than all the 36 cases. When this exception does not apply, the 36 cases work.

0. All method call sites mirror
   move and lease declared in
   method signatures.

1. dst (unmarked) = src (unmarked)

   Ordinary assignment.

2. dst (unmarked) = src (lease)

   Downgrading assignment.
   Ownership metadata is lost.

   Backwards compatibility.
   Warning: "Downgrading assignment".

3. dst (unmarked) = src (move)

   Downgrading assignment.
   Ownership metadata is lost.

   Backwards compatibility.
   Warning: "Downgrading assignment".

4. dst (unmarked) = lease src (unmarked)

   Compilation error: cannot lease-assign
   unmarked source to unmarked destination.
   Use ordinary assignment.

5. dst (unmarked) = lease src (lease)

   Compilation error: cannot lease-assign to unmarked
   destination. Use downgrading assignment.

6. dst (unmarked) = lease src (move)

   Compilation error: cannot lease-assign to unmarked
   destination. Use downgrading assignment.

7. dst (unmarked) = move src (unmarked)

   Compilation error: cannot move-assign
   unmarked source to unmarked destination.
   Use ordinary assignment.

8. dst (unmarked) = move src (lease)

   Compilation error: cannot move-assign
   source marked with 'lease' to
   unmarked destination.
   Use downgrading assignment.

9. dst (unmarked) = move src (move)

   Compilation error: cannot move-assign to unmarked
   destination. Use downgrading assignment.

10. dst (lease) = src (unmarked)

    Upgrading assignment.
    Ownership metadata is introduced.

    dst is tracked further as marked with lease.

    Backwards compatibility.
    Warning: "Upgrading assignment"
    (except when src is a literal or constructor call)

11. dst (lease) = src (lease)

    Compilation error: cannot assign source
    marked with lease to destination marked
    with lease. Use lease-assignment.

12. dst (lease) = src (move)

    Compilation error: cannot assign source
    marked with move to destination marked
    with lease. Use lease-assignment.

13. dst (lease) = lease src (unmarked)

    Upgrading lease-assignment.
    Ownership metadata is introduced.

    dst is tracked further as marked with lease.

    Backwards compatibility.
    Warning: "Upgrading lease-assignment".
    (except when src is a literal or constructor call)

    /*
    Compilation error: cannot lease-assign
    unmarked source to marked destination.
    Use upgrading assignment.
    */

14. dst (lease) = lease src (lease)

    Lease assignment.

    dst is tracked further as marked with lease.

15. dst (lease) = lease src (move)

    Lease assignment.

    dst is tracked further as marked with lease.

16. dst (lease) = move src (unmarked)

    Compilation error: cannot move-assign
    unmarked source to destination marked with 'lease'.

17. dst (lease) = move src (lease)

    Compilation error: cannot move-assign
    source marked with 'lease'
    to destination marked with 'lease'.
    Use lease-assignment.

18. dst (lease) = move src (move)

    Compilation error: cannot move-assign
    to destination marked with 'lease'.
    Use lease-assignment.

19. dst (move) = src (unmarked)

    Upgrading assignment.
    Ownership metadata is introduced.

    dst is tracked further as marked with move.

    Backwards compatibility.
    Warning: "Upgrading assignment".
    (except when src is a literal or constructor call)

20. dst (move) = src (lease)

    Compilation error: cannot assign source
    marked with lease to destination
    marked with move.

21. dst (move) = src (move)

    Compilation error: cannot assign source marked
    with move to destination marked with move.
    Use move assignment.

22. dst (move) = lease src (unmarked)

    Compilation error: cannot lease-assign
    unmarked source to marked destination.
    Use upgrading assignment.

23. dst (move) = lease src (lease)

    Compilation error: cannot lease-assign to
    destination marked with move

24. dst (move) = lease src (move)

    Compilation error: cannot lease-assign to
    destination marked with move.
    Use move assignment.

25. dst (move) = move src (unmarked)

    Upgrading move-assignment.
    Ownership metadata is introduced.

    dst is tracked further as marked with move.

    If src is a property or field, the compiler
    assigns default(TResource) to src.
    If in addition src is a property, it must
    expose a setter accessible at the line
    with the assignment, otherwise that is a
    compilation error.

    Backwards compatibility.
    Warning: "Upgrading move-assignment".
    (except when src is a literal or constructor call)

    /*
    Compilation error: cannot move-assign
    unmarked source to marked destination.
    Use upgrading assignment.
    */

26. dst (move) = move src (lease)

    Compilation error: cannot move
    source marked with 'lease'

27. dst (move) = move src (move)

    Move assignment.

    dst is tracked further as marked with move.

    If src is a property or field, the compiler
    assigns default(TResource) to src.
    If src is a property, it must
    expose a setter accessible at the line
    with the assignment, otherwise that is a
    compilation error.

28. var dst = src (unmarked)

    Ordinary assignment.

29. var dst = src (lease)

    Compilation error: cannot assign source
    marked with lease to destination
    declared as var, use lease-assignment

30. var dst = src (move)

    Compilation error: cannot assign source
    marked with move to destination
    declared as var, use lease- or
    move-assignment

31. var dst = lease src (unmarked)

    Compilation error: cannot lease-assign
    unmarked source to destination
    declared as var, use upgrading
    assignment.

32. var dst = lease src (lease)

    Lease assignment.

    dst is tracked further as marked with lease.

33. var dst = lease src (move)

    Lease assignment.

    dst is tracked further as marked with lease.

34. var dst = move src (unmarked)

    Compilation error: cannot move-assign
    unmarked source to destination
    declared as var, use upgrading
    assignment.

35. var dst = move src (lease)

    Compilation error: cannot move
    source marked with 'lease' (use lease-assignment)

36. var dst = move src (move)

    Move assignment.

    dst is tracked further as marked with move.

    If src is a property or field, the compiler
    assigns default(TResource) to src.
    If in addition src is a property, it must
    expose a setter accessible at the line
    with the assignment, otherwise that is a
    compilation error.

Moving assignment for local variables

Moving a local variable marks it as uninitialized:

int Use(move int tool)
{
    Console.WriteLine(tool);
    return tool;
}

public void Run()
{
    move int silverlight = 5;

    var win8 = move silverlight;

    //compilation error CS0165:
    //Use of unassigned local variable 'silverlight'
    Use(move silverlight);
}

This is OK as we initialize silverlight after moving:

public void Run()
{
    move int silverlight = 5;

    var win8 = move silverlight;

    silverlight = 6;

    //OK
    Use(move silverlight);
}

Capturing a local variable by a closure is not allowed if that variable is moved outside the closure (before or after):

move int a = 0; 
move int b = move a;

Task.Run(() => 
{ 
    //compilation error: cannot capture variable 'a'
    //because it is moved outside the closure
    int i = a; 
    //...
}, TaskCreationOptions.LongRunning);

move int a = 0; 

Task.Run(() => 
{ 
    //compilation error: cannot capture variable 'a'
    //because it is moved outside the closure
    //(otherwise we would allow races)
    int i = a; 
    //...
}, TaskCreationOptions.LongRunning);

move int b = move a;

The existing control flow analysis would be reused as much as possible:

move int a = 0; 

int k = 5;
if (k > 0)
{
    //ok
    move int b = move a;
}
else
{
    //ok
    move int d = move a;
}

//compilation error CS0165:
//Use of unassigned local variable 'a'
move int c = move a;

If a captured variable is moved inside a closure, accessing the variable is not allowed after that:

move int a = 0; 

//OK, case 3
int b = a;

Task.Run(() => 
{ 
    move int c = move a;
    
    //compilation error CS0165:
    //Use of unassigned local variable 'a'
    int d = a;

    //...
}, TaskCreationOptions.LongRunning);

//compilation error CS0165:
//Use of unassigned local variable 'a'
int e = a;

When a local variable is managed by using, it becomes observable for the code generated by using. That forces the compiler to assign default(TResource) to the variable after it is moved:

using(FileStream fs = File.OpenWrite(path))
{    
    WriteFileHeader(fs);

    StartLogging(move fs);//case 25
}//calls fs.Dispose() only if WriteFileHeader(...) throws

In other cases moved local variables and method parameters are just marked as uninitialized and the compiler requires them to be initialized again in order to be read after the moving assignment.

Some examples:

//case 10, ok
lease int src = 1;

//case 29
//Compilation error: cannot assign source 
//marked with `lease` to destination
//declared as `var`, use lease-assignment
var dst = src;

//case 32, ok
var dst2 = lease src;

//case 2, ok
//downgrade from lease to unmarked
int dst3 = src;

//case 5
//Compilation error: cannot lease-assign to unmarked 
//destination. Use downgrading assignment.
int dst4 = lease src;

//case 11
//Compilation error: cannot assign source 
//marked with lease to destination marked 
//with lease. Use lease-assignment. 
lease int dst5 = src; 

//case 14, ok
lease int dst6 = lease src; 

//case 26
//Compilation error: cannot move 
//source marked with 'lease'
move int dst6 = move src; 

//case 1, ok
int a = 1;

//case 34
//Compilation error: cannot move-assign  
//unmarked source to destination
//declared as `var`, use upgrading 
//assignment
var b = move a; 

//case 1, ok
int c = 1;

//case 31
//Compilation error: cannot lease-assign 
//unmarked source to destination
//declared as `var`, use upgrading 
//assignment.
var d = lease c; 

Variables that are not marked:

//a is not marked with 'lease' or 
//'move' but can be moved (backwards compatibility)
//case 1, ok
int a = 1;

//case 25, Upgrading move-assignment
move int b = move a;

//a2 is not marked with 'lease' or 'move' 
//and its value can be lease-assigned to other 
//variable (backwards compatibility)
//case 1, ok
int a2 = 1;

//case 13, Upgrading lease-assignment
lease b2 = lease a2;

Move and lease as field and property declaration attributes

In declarations of class fields and properties,
move and lease act as annotations describing
whether the field/property owns its value:

sealed class Holder : IDisposable
{
    //_resource owns its value 
    move readonly Resource _resource;

    //Resource2 owns its value 
    move Resource Resource2 { get; }

    //_externalResource does not own its value 
    lease readonly Resource _externalResource;

    //ExternalResource2 does not own its value 
    lease Resource ExternalResource2 { get; }

    public void Dispose()
    {
        if(_resource!=null)
        {
            _resource.Dispose()
        }

        if(Resource2!=null)
        {
            Resource2.Dispose()
        }

        if(_externalResource!=null)
        {
            //compilation error: cannot dispose
            //of _externalResource as it leases 
            //its value 
            _externalResource.Dispose();
        }

        if(ExternalResource2!=null)
        {
            //compilation error: cannot dispose 
            //of ExternalResource2 as it leases 
            //its value 
            ExternalResource2.Dispose();
        }
    }
}

Non-readonly IDisposable fields and non-get-only IDisposable auto properties declared with move
can be assigned to many times, potentially overwriting their previous values. Special care must be taken to avoid leaks in such cases:

sealed class Holder : IDisposable
{
    //Owner owns its value 
    move Resource Owner
    {
        get => _owner;
        set
        {
            if(!ReferenceEquals(_owner, null) &&
               !ReferenceEquals(value, _owner))
            {
                //release previous value
                _owner.Dispose();
            }
            _owner = move value;
        }
    }
    move Resource _owner;

    public void Dispose()
    {
        if(Owner!=null)
        {
            Owner.Dispose();
            Owner = null;
        }
    }
}

When a property of a disposable type is marked as move and declares automatically implemented getter and setter, the compiler generates the setter as in the example above.

Moving values from owning properties and fields

If a property or field is marked with move and thus owns its value, it is allowed to move that value to another owner:

sealed class Holder : IDisposable
{
    move Resource Res
    {
        get => _res;
        set
        {
            if(!ReferenceEquals(_res, null) &&
               !ReferenceEquals(value, _res))
            {
                _res.Dispose();
            }
            _res = move value;
        }
    }
    move Resource _res;

    public Holder(move Resource r)
    {
        Res = move r;
    }

    public void Dispose()
    {
        if(Res!=null)
        {
            Res.Dispose();
            Res = null;
        }
    }
}

void Use()
{
    Holder h1 = new Holder(
        move Producer.Instance.MakeResource()
    );

    Holder h2 = new Holder(move h1.Res);
    
    Debug.Assert(ReferenceEquals(h1.Res, null));

    //now h1 does not own anything,
    //h2 owns the resource
}

After moving h1.Res to h2.Res, the compiler assigns default(Resource) to h1.Res.
If the source of a moving assignment is a property, the property must have a setter with enough visibility to be called at the line with the moving assignment, otherwise that is a compilation error.

Specifying move or lease for property setters and getters is not supported, these keywords always apply to the whole property. When fine-grained control over access modifiers or implementations of resource accessors is needed, it is possible to implement the accessors as methods:

sealed class Holder : IDisposable
{
    move Resource _res;

    public lease Resource GetRes()
    {
        return lease _res;
    }
   
    private void SetRes(move Resource value)
    {
        if(!ReferenceEquals(_res, null) &&
           !ReferenceEquals(value, _res))
        {
            _res.Dispose();
        }
        _res = move value;
    }

    //moves the resource out of this class
    protected move Resource Move()
    {
        return move _res;
    }

    public Holder(move Resource r)
    {
        _res = move r;
    }

    public void Dispose()
    {
        if(_res!=null)
        {
            _res.Dispose();
            _res = null;
        }
    }
}

As readonly fields and get-only auto properties marked with move cannot be assigned to, it is prohibited to move values from them. They are move-assigned their values in constructors and become lifelong owners:

sealed class Holder : IDisposable
{
    public move readonly Resource Res;

    public Holder(move Resource r)
    {
        Res = move r;
    }

    public void Dispose()
    {
        if(Res!=null)
        {
            Res.Dispose()
        }
    }
}

void Use()
{
    Holder h1 = new Holder(
        move Producer.Instance.MakeResource()
    );

    //compilation error: h1.Res is readonly and cannot be moved 
    Holder h2 = new Holder(move h1.Res);
}

void Use2()
{
    Holder h1 = new Holder(
        move Producer.Instance.MakeResource()
    );

    //OK, case 33
    //same as lease Resource r = lease h1.Res
    var r = lease h1.Res; 

    //compilation error: r is marked with lease and cannot be moved 
    //case 26
    Holder h2 = new Holder(move r)
}

void Use3()
{
    Holder h1 = new Holder(
        move Producer.Instance.MakeResource()
    );

    //case 3 
    //Downgrading move to unmarked
    Resource r = h1.Res;

    //case 25
    //Upgrading unmarked to move
    //compiles, all protections bypassed
    Holder h2 = new Holder(move r)
}

void Use4()
{
    Holder h1 = new Holder(
        move Producer.Instance.MakeResource()
    );

    //case 3 
    //Downgrading move to unmarked
    Resource r = h1.Res;

    //case 19
    //Upgrading unmarked to move
    move Resource r2 = r;

    //case 27
    //compiles, all protections bypassed
    Holder h2 = new Holder(move r2)
}

Method parameters and return values

move and lease at declaration vs call sites

If a method signature contains move or lease, then all call sites must exactly "mirror" the same keywords, similarly to the use of ref and out with method parameters. For example, methods that return values marked as move or lease cannot be called without those keywords:

move FileStream WriteSection(
    move FileStream fs, 
    Section section)
{
    fs.Write(/*...*/);
    fs.Write(/*...*/);
    fs.Write(/*...*/);

    return move fs;
}
 
void Caller()
{
    Section currentSection = /* */;

    //case 0
    //compilation error: WriteSection(...) 
    //returns value by move. 
    //Use move-assignment
    _fileStream = WriteSection(
        move _fileStream,
        currentSection
    );
}

void Caller2()
{
    foreach (Section section in _sections)
    {
         //case 0, ok
        _fileStream = move WriteSection(
            move _fileStream,
            section
        );
    }
}

Move-parameter

The compiler resets observable sources passed into methods as actual move-arguments:

void StartLogging(move FileStream s)
{
//
}
 
void Caller()
{
    StartLogging(move _fileStream);
   
    //1. load _fileStream on the stack
    //2. _fileStream = null;
    //3. call StartLogging
}

_fileStream in the snippet above is a class field and its value can be observed even after moving _fileStream into the method call. For exception safety, all resetting assignments must be done after loading all actual arguments on the stack, but before transferring control to the callee.

In the example below one of the arguments throws:

void StartLogging(move FileStream s, int i)
{
//
}
 
void Caller()
{
    int k = 0;
    StartLogging(
        move _fileStream, 
        1/k //division by zero
    );
    Debug.Assert(!ReferenceEquals(_fileStream, null));
}

but _fileStream is not assigned null because the exception occurs while evaluating and loading actual arguments on the stack and before any resetting assignment.

If the callee's code starts executing, the callee becomes the owner of any values passed into it by moving.
The callee is then responsible for disposing of any IDisposable values it received, regardless of exceptions thrown while it executes:

void StartLogging(move FileStream s, int i)
{
    using(s)
    {
        if(i < 0) throw new ArgumentOutOfRangeException(nameof(i));
        //other checks 

        //other processing that needs s
    }

    //other processing that does not need s
}

void StartLogging2(move FileStream s, int i)
{
    using(s)
    {
        if(i < 0) throw new ArgumentOutOfRangeException(nameof(i));
        //other checks 
 
        //s normally moves into this call
        StartLogging(move s, i + 1);
   
    }//...except when something inside this using went wrong
   
    //other processing that does not need s
}
 
void Caller()
{
    StartLogging(move _fileStream, 1);

    StartLogging2(move _fileStream, 1);
}

When moving unobservable sources into methods, the sources are just marked as uninitialized:

void StartLogging(move FileStream s)
{
//
}
 
void Caller()
{
    move FileStream fs = File.OpenWrite(path);

    StartLogging(move fs);

    //compilation error CS0165: Use of 
    //unassigned local variable 'fs'
    fs.Close();
}

In the snippet above using or try-finally are not required. Valid fs moves into StartLogging(...) and is owned further by that method. If File.OpenWrite(..) throws, we do not have valid file streams.

Moving assignments in the using-statement

Unobservable sources of move-assignments are marked as uninitialized after being moved.
When writing exception-safe code that needs to dispose of a source that potentially has not been moved due to exceptions, use the using-statement:

void Caller()
{
    move FileStream fileStream = /* fileStream is a 
    local variable and it is normally 
    unobservable after being moved
    */;

    //here fileStream has not yet been moved
    using(fileStream)
    {
        int k = 0;

        StartLogging(
            move fileStream, 
            1/k //division by zero
        );  
              
        //fileStream is marked as uninitialized              
        //and we cannot reference it here directly.                

        //compilation error CS0165:
        //Use of unassigned local variable 'fileStream'
        var pos = fileStream.Position;
    }   
}

In the snippet above, fileStream is managed by the using-statement. This makes fileStream observable
and forces the compiler to null it out after evaluating and loading on the stack all the actual arguments of
StartLogging(...). fileStream is still marked as uninitialized after the moving assignment, and we cannot
read fileStream directly without first assigning a value to it. But the using-statement "captured"
fileStream before the moving assignment and the statement is allowed to read and dispose of fileStream in its generated code. The try-catch and try-finally blocks are not special cased to access possibly moved variables and the using-statement is the only way to definitely dispose of possibly moved sources:

void Caller()
{
    move FileStream fileStream = /* */;
    try
    {
        int k = 0;
        StartLogging(
            move fileStream, 
            1/k //division by zero
        );  
              
        //compilation error CS0165:
        //Use of unassigned local variable 'fileStream'
        var pos = fileStream.Position;
    }  
    catch
    {
        //compilation error CS0165:
        //Use of unassigned local variable 'fileStream'
        var pos1 = fileStream.Position;
    }
    finally
    {
        //compilation error CS0165:
        //Use of unassigned local variable 'fileStream'
        if(fileStream!=null)
            fileStream.Dispose();
    }
}

Move-out parameter

Formal method arguments declared as both out and move move the argument's value and ownership from the callee to the caller:

void Scan(FileStream fs, 
    string pattern, 
    move out Match firstMatch)
{
//
}

void Caller()
{
    FileStream fs = /* */;   

    move Match firstMatch;
    Scan(fs, "*ast*", move out firstMatch)
    //
}

How exactly the callee behaves in case of exceptions and what it assigns to its out move arguments is specified by users.

The caller becomes the resource owner after the callee returns. If the caller neither moves nor disposes of the resource, that is a compilation error:

class Match : IDisposable
{
//
}

void Caller()
{
    FileStream fs = /* */;  
    move Match firstMatch;

    Scan(fs, 
        "*ast*", 
        move out firstMatch)

    //compilation error: match is 
    //neither moved nor disposed of
}

class Holder : IDisposable
{
    move Match _match;
    FileStream _fs;

    //...

    //ok
    void Caller()
    {
        move Match match;

        Scan(_fs, 
            "*ast*", 
            move out match);

        _match = move match;
    }

    //ok
    void Caller2()
    {
        Scan(_fs, 
            "*ast*", 
            move out _match);
    }

    //ok
    void Caller3()
    {
        move Match match;

        Scan(_fs, 
            "*ast*", 
            move out match);
        
        match?.Dispose();
    }

    //ok
    void Caller4()
    {
        move Match match;

        Scan(_fs, 
            "*ast*", 
            move out match);
        
        ExternalHolder.Instance.Add(
            move match
        );
    }

    //...
}

Move-ref parameter

When a method signature contains an argument declared as both ref and move:

1. The actual argument's value and ownership move into the method when transferring control to the method

2. The formal argument's value and ownership move from the method to the actual argument when returning control from the method.

The value returned by the method in a move-ref argument may differ from the value passed into the method in the same argument.

Besides, the method may leave the value without changes or return null after disposing of the original value or moving it to another owner.

The compiler never resets actual move-ref arguments automatically at call sites, even when those arguments are observable after being moved. Instead, the callee is fully responsible for:

• Managing IDisposable values passed into the callee in move-ref arguments
• Setting move-ref arguments accordingly in all cases, including exceptions occurring while the callee executes.

In the example below, FindNext(...) acts like an iterator when called in a loop. It fetches the next
iterated value, returns it to the caller, and takes care of disposing of the previous iterated value, so that callers do not need to worry about resource management:

class Match : IDisposable
{
//
}
 
void FindNext(FileStream fs, 
    string pattern, 
    move ref Match match)
{
    if(match==null)
    {
        match = move /* find first match */
    }
    else
    {
        move Match nextMatch = null;
        try
        {
            nextMatch = /* find next match */
        }
        finally
        {
            //dispose of the previous match
            match.Dispose();

            //return the new match
            match = move nextMatch;
        }        
    }
}

void Caller()
{
    using(FileStream fs = /* */)
    {
        Match match = null;     
        while(true)
        {
            FindNext(fs,
                "*ast*", 
                move ref match 
            );
         
            if(match == null)
                break;

            Console.WriteLine(match);   
        }
    }
}

The callee may move its move-ref arguments to other variables. As actual move-ref arguments can be observed after being moved by the callee, the compiler resets them. However, from the callee's perspective, such arguments are uninitialized after being moved:

void BlackHole(
    move ref Match a, 
    move ref Match b)
{
    using(a)
    using(b)
    {
        AnotherMethod(move a);
        a = default(Match);// <-- compiler
        
        //compilation error CS0165:
        //Use of unassigned local variable 'a'        
        move Match c = move a;


        move Match m = move b;
        b = default(Match);// <-- compiler
        m?.Dispose();
    }
}

void Caller()
{
    move Match match1 = new Match();
    move Match match2 = new Match();

    BlackHole(
        move ref match1,
        move ref match2,
    );

    //the caller can access actual move-ref 
    //arguments after the callee returns,
    //this means reading returned values    
    Debug.Assert(match1 == null);
    Debug.Assert(match2 == null);
}

Move return

Methods returning a value marked as move return the value and its ownership to the caller.

This is the most popular potential use case for this proposal, as a huge number of APIs (e.g. File.OpenWrite) assume this semantics.

If a method returns an IDisposable by moving, the caller should either dispose of that instance directly (by calling Dispose()) or move the instance to another owner. The caller cannot ignore the returned value.

Example

Fabricam is a cloud provider of computing power for solving cryptographic problems. It operates dedicated ASIC-based hardware that implements each algorithm most efficiently. Clients are billed based on time and power. As most problems are time-consuming and costly, it is
important to manage pools efficiently. Because Fabricam implemented their client library in C# N using the move keyword, the clients will never forget to eagerly dispose of allocated pools:

//compilation error: AllocatePool(...) return value is marked as move
void ClientCode()
{
    var pool = Fabricam.Client.AllocatePool(
        Kind.Sha256, 
        //...
        //
    );
 
    //use pool
}

//compilation error: pool is marked as move 
//and implements IDisposable. Dispose of the 
//pool or move it.
void ClientCode()
{
    var pool = move Fabricam.Client.AllocatePool(
        Kind.Sha256, 
        //...
        //
    );
 
    //use pool
}

//OK
void ClientCode()
{
    using(var pool = move Fabricam.Client.AllocatePool(
        Kind.Sha256, 
        //...
        //
    ))
    {
        //use pool
    }
}

Lease-arguments

Method arguments marked as lease transfer values without transferring ownership.

Example

When an IDE saves its workspace state, it allows all extensions to do the same. The state is saved in a single file of a specified format. The IDE creates that file, writes a file header, writes its own state, then calls SaveState(...) implemented by each extension. Passing a lease-argument into SaveState(...)
clearly expresses the IDE-extension contract: the IDE manages the argument:

abstract class ExtensionBase
{
    void abstract SaveState(
        lease TextWriter writer);
}

class BadExtension : ExtensionBase
{
    void override SaveState(
        lease TextWriter writer)
    {
        //compilation error: cannot 
        //dispose of 'writer' as it is 
        //marked as 'lease'
        writer.Dispose();

        //compilation error: cannot 
        //dispose of 'writer' as it is 
        //marked as 'lease'
        using(writer)
        {
        }

        //compilation error: cannot 
        //move 'writer' as it is 
        //marked as 'lease'
        WritersSink(move writer);
    }
}

Methods are not allowed to prolong the lifetime of leased arguments

Consider that you take a lake house on lease for 30 days. You may share it with your friends, and even lease [0..all] rooms to other people for [0..30] days, but regardless of how you allocate the space-time resources, you have to return the keys to the owner in 30 days. Any new contracts between you and 3rd parties must not violate the contract between you and the owner.

A method m that receives a lease parameter lp is allowed to lease lp to other methods that it calls. m is not allowed to prolong the lifetime of lp by saving lp in any class fields, properties, or capturing lp by closures:

class BadExtension : ExtensionBase
{
    lease TextWriter _writer;
    TextWriter _writer2;

    void override SaveState(
        lease TextWriter writer)
    {
        Task.Run(() => 
        { 
            System.Threading.Thread.Sleep(5000);

            //compilation error: cannot capture
            //lease-arguments by closures
            writer.Write(/*...*/);

            //...
        }, TaskCreationOptions.LongRunning);

        
        //compilation error: cannot 
        //save lease-arguments in 
        //class fields and properties
        _writer = lease writer;

        //compilation error: cannot 
        //save lease-arguments in 
        //class fields and properties
        _writer2 = writer;

        //ok, downgrade from lease to unmarked
        TextWriter w = writer;

        //all protections bypassed
        _writer2 = w;
    }
}

However, class constructors may save its lease-arguments in their own fields and properties. When callers pass lease-arguments into a class constructor, the callers allow the constructed instance to use the passed lease-arguments for at least as long as the callers themselves reference the instance and use it:

public class Search 
{
    lease FileStream _file;

    public Search(lease FileStream file, 
        string pattern)
    {
        //this is allowed
        _file = lease file;
        
        //this is still not allowed
        Task.Run(() => 
        { 
            System.Threading.Thread.Sleep(5000);

            //compilation error: cannot capture
            //lease-arguments by closures
            file.Write(/*...*/);

            //...
        }, TaskCreationOptions.LongRunning);
    }
    
    public Match FindNext()
    {
      //
    }
}

//...

void EnumMatches()
{
    using(move FileStream fs = File.OpenRead(_path))
    {
        var s = new Search(lease fs, "*ast*");

        Match m;
        while((m = s.FindNext())!=null)
        {
            Console.WriteLine(m);
        }
    }
}

While callees may not prolong the lifetime of lease-arguments, callers should guarantee that passed actual lease-arguments are alive for at least as long as the callee executes.

Lease-returns and lease-out arguments

Lease-returns and lease-out arguments mean that the callee allows the caller to use them, but not more:

void Scan(FileStream fs, 
    string pattern, 
    lease out Match match)
{
//implementation
}

void Caller()
{
    lease Match match;
    Scan(_fs, "*ast*", lease out match);
   
    Console.WriteLine(match);
    
    //compilation error: cannot 
    //dispose of 'match' as it is 
    //marked as 'lease'
    match.Dispose();
}

lease Match Scan(FileStream fs, 
    string pattern)
{
//implementation
}

void Caller()
{    
    var match = lease Scan(_fs, "*ast*");
   
    Console.WriteLine(match);
    
    //compilation error: cannot 
    //dispose of 'match' as it is 
    //marked as 'lease'
    match.Dispose();
}

Lease-ref arguments

lease-ref arguments are not allowed:

//compilation error: lease-ref 
//arguments are not supported
void FindNext(FileStream fs, 
    lease ref Match match)
{
//implementation
}

Interfaces and delegates

Whenever move or lease are used in declarations of properties in interfaces, all implementations are forced to implement such properties with exactly the same specifiers:

interface IHolder : IDisposable
{
    move Resource InternalResource {get;set;}

    lease Resource ExternalResource {get;set;}
}

sealed class Holder : IHolder
{
    //compilation error: missing `move`
    public Resource InternalResource {get; set;}

    //ok
    public move Resource InternalResource {get; set;}

    //compilation error: missing `lease`
    public Resource ExternalResource {get; set;}

    //ok
    public lease Resource ExternalResource {get; set;}

    public void Dispose()
    {
        if(InternalResource!=null)
        {
            InternalResource.Dispose();
            InternalResource = null;
        }
    }
}

move or lease used in method signatures in interfaces force all implementations to do exactly the same as well:

interface IHolder : IDisposable
{
    lease Resource GetRes();

    void SetRes(move Resource value);
}

sealed class Holder : IHolder
{
    move Resource _res;

    public Holder(move Resource r)
    {
        _res = move r;
    }

    //compilation error: missing `lease`
    public Resource GetRes()
    {
        return _res;
    }

    //ok
    public lease Resource GetRes()
    {
        return lease _res;
    }

    //compilation error: missing `move`
    public void SetRes(Resource value)
    {
    }
   
    //ok
    public void SetRes(move Resource value)
    {
        if(!ReferenceEquals(_res, null) &&
           !ReferenceEquals(value, _res))
        {
            _res.Dispose();
        }
        _res = move value;
    }

    public void Dispose()
    {
        if(_res!=null)
        {
            _res.Dispose();
            _res = null;
        }
    }
}

If a delegate is declared using move or lease in its signature, then it can be assigned to only methods, anonymous delegates, lambda expressions that have exactly matching move or lease in their signatures:

delegate void PaperShredder(move Document doc);

class TestClass
{
    static void Main()
    {
        //ok
        PaperShredder p = delegate(move Document d)
        {
            d.Dispose();
        };

        //ok
        p = new PaperShredder(TestClass.Shred);

        //ok
        p = (move Document d) => { d.Dispose(); }
    }

    static void Shred(move Document d)
    {
        d.Dispose();
    }
}

Backwards compatibility

Upgrading and downgrading assignments

If one of the sides, source or destination, is marked with move or lease while the opposite side is not, the associated assignments will be upgrading or downgrading assignments.

New code should avoid upgrading and downgrading assignments internally.

All upgrading and downgrading assignments should only occur at the interface between new and legacy code.

Developers are responsible for manually verifying that move and lease declaration specifiers visible at the new-vs-legacy interface match the expectations and assumptions of the legacy code.

Using upgrading and downgrading assignments allows to circumvent the rules of resource management and create invalid code. The compiler generates warnings when it encounters upgrading or downgrading
assignments. Each such warning should be reviewed and opted-out manually.

Compiling new source with legacy source

Methods, interfaces, delegates, class properties and fields that use move or lease in their signatures or declarations require "mirroring" move and lease at all method call sites and all interface/delegate implementations. If legacy source needs to use the new method MakeDryMartini(...), either rewrite the legacy source to use move at all call sites as MakeDryMartini(...) requires or write the adapter method
MakeDryMartiniForLegacyCallers(...) without move and lease in its signature:

move DryMartini MakeDryMartini(
    move BeefeaterGin gin, 
    move DryVermouth vermouth,
    move OrangeBitters orange)
{
//
}

DryMartini MakeDryMartiniForLegacyCallers(
    BeefeaterGin gin, 
    DryVermouth vermouth,
    OrangeBitters orange)
{
    //case 3  
    //return: downgrade move to unmarked
    return move MakeDryMartini(
        //case 25, upgrade unmarked to move
        move gin,

        //case 25, upgrade unmarked to move
        move vermouth,

        //case 25, upgrade unmarked to move
        move orange
    );
}

Pass variables marked with lease or move into existing methods

void ExistingMethod(IDisposable res)
{
//
}

void Run()
{
    lease IDisposable externalRes = lease GetExternalResource();
    //case 2, downgrade lease to unmarked
    ExistingMethod(externalRes);

    move IDisposable res = move GetInternalResource();
    //case 3, downgrade move to unmarked
    ExistingMethod(res);
}

One more example:

move string s1 = "s1";

//OK, downgrade move to unmarked
Console.WriteLine(s1);

lease string s2 = "s2";

//OK, downgrade lease to unmarked
Console.WriteLine(s2);

Assign variables marked with lease or move to class fields and properties of existing classes

class ExistingClass
{
    public IDisposable Resource {get;set;}
}

void Run()
{
    var existing = new ExistingClass();

    lease IDisposable externalRes = lease GetExternalResource();
    //case 2, downgrade lease to unmarked
    existing.Resource = externalRes;

    move IDisposable res = move GetInternalResource();    
    //case 3, downgrade move to unmarked
    existing.Resource = res;
}

Assign return values of existing methods to variables marked with lease or move

IDisposable ExistingMethod()
{
//
}

void ExistingMethod2(out IDisposable r)
{
//
}

void Run()
{
    //case 10, upgrade unmarked to lease
    lease IDisposable a = ExistingMethod();

    //case 19, upgrade unmarked to move
    move IDisposable b = ExistingMethod();

    lease IDisposable c;
    //case 10, upgrade unmarked to lease
    ExistingMethod2(out c);

    move IDisposable d;
    //case 19, upgrade unmarked to move
    ExistingMethod2(out d);
}

Allow existing code to call methods that accept parameters marked with lease or move

This is impossible directly, see "Compiling new source with legacy source"

Allow existing code to call methods that return values marked with lease or move

This is impossible directly, see "Compiling new source with legacy source"

Read values of fields and properties of existing classes into variables marked with lease or move

class ExistingClass
{
    public IDisposable Resource { get; set; }
}

void Run()
{
    var existing = new ExistingClass();

    //case 10, upgrade unmarked to lease
    lease IDisposable externalRes = existing.Resource;
    
    //case 19, upgrade unmarked to move
    move IDisposable res = existing.Resource;
}

Examples

Basic synchronization using System.Threading.Monitor

One way to simplify the use of System.Monitor is to implement a simple disposable wrapper, like that is done in sqlite-net:

private class LockWrapper : IDisposable
{
    object _lockPoint;

    public LockWrapper(object lockPoint)
    {
        _lockPoint = lockPoint;
        Monitor.Enter (_lockPoint);
    }

    public void Dispose()
    {
        Monitor.Exit (_lockPoint);
    }
}

It is possible to evolve this pattern by adding static type safety, either using generics or creating multiple subclasses. Methods that require exclusive access to a synchronized resource then require an instance of
LockWrapper:

void IAccessCollectionA(LockWrapper lockForCollectionA)
{
}

void IAccessCollectionAToo(LockWrapper lockForCollectionA)
{
}

Everything so far plays well, especially thanks to the using-statement.

Still there is a problem, LockWrapper is a reference type and it can be copied easily:

void IAccessCollectionA(LockWrapper lockForCollectionA)
{
}

void IAccessCollectionAToo(LockWrapper lockForCollectionA)
{
}

void BuggyButCompiles()
{
    using(var lockA = new LockWrapper(_collectionA))
    {
        Task.Run(() => 
        { 
            while(true)
            {
                IAccessCollectionA(lockA);
                System.Threading.Thread.Sleep(50);
            }
        }, TaskCreationOptions.LongRunning);

        while(true)
        {
            IAccessCollectionAToo(lockA);
            System.Threading.Thread.Sleep(50);
        }
    }
}

Though LockWrapper correctly locks a resource across all threads, we failed to communicate the constraint that an instance of LockWrapper represents the permission to exclusively access the locked resource, and thus LockWrapper instances themselves require exclusive ownership:

move LockWrapper IAccessCollectionA(move LockWrapper lockForCollectionA)
{
    //access collection A

    //return ownership to the caller
    return move lockForCollectionA;
}

move LockWrapper IAccessCollectionAToo(move LockWrapper lockForCollectionA)
{
    //access collection A

    //return ownership to the caller
    return move lockForCollectionA;
}

class TestClass
{
    move LockWrapper LockCollectionA()
    {
        return new LockWrapper(_collectionA);
    }

    void BuggyButDoesNotCompile()
    {
        using(var lockA = move LockCollectionA())
        {
            Task.Run(() => 
            { 
                while(true)
                {
                    //compilation error: cannot capture variable 'lockA'
                    //because it is moved outside the closure
                    lockA = move IAccessCollectionA(move lockA);
                    System.Threading.Thread.Sleep(50);
                }
            }, TaskCreationOptions.LongRunning);

            while(true)
            {
                lockA = move IAccessCollectionAToo(move lockA);
                System.Threading.Thread.Sleep(50);
            }
        }
    }
}

With the second implementation, we get a compile-time error.

The lifetimes of LockWrapper instances in the first implementation can be managed only using the using-statement. Everything else is too hard and error-prone.

The second implementation encourages exploring other possibilities too, like holding a LockWrapper in a class field:

class CollectionOperation : IDisposable
{
    readonly move LockWrapper _collectionLock;

    public CollectionOperation(move LockWrapper l)
    {
        _collectionLock = move l;
    }

    public void Execute()
    {
    //
    }

    public void Dispose()
    {
        _collectionLock?.Dispose();
    }
}

Protecting confidential information with move

Consider an application that processes confidential data. The data is always stored encrypted on disk and only exists as plaintext in RAM. As soon as a data processing task is complete, the data in RAM is encrypted and saved. As an additional precaution, the application erases plaintext in RAM in order to prevent accidental leaks (accidental crash dumps, heartbleed, other vulnerabilities).

The application uses a custom class called SecureStr. SecureStr keeps plaintext in RAM. SecureStr implements IDisposable and wipes its data from RAM on disposing. SecureStr pins its underlying buffer in memory in order to prevent the GC from creating deep copies while compacting object heaps.

Assume that the application keeps its data as json. A file is first decrypted into a SecureStr instance containing json. Then json is parsed into tokens. Some tokens contain actual content:

public sealed class Token : IDisposable
{
    public move SecureStr Content { get; set; }
   
    //...
}

Once json has been parsed into tokens, the buffer with json is no longer used and the application disposes of it, erasing its data from memory.

The token sequence is then transformed into an AST. Leaf nodes of the AST contain actual content (the same content as respective content tokens contain):

public class Leaf : Node
{
    public move SecureStr Content { get; set; }
   
    //...

    protected override void Dispose(bool disposing)
    {
        //...
    }
}

Once the AST has been built, the tokens are no longer used and the application disposes of them. There is no need to copy the content from content tokens to AST leaves. Instead, Token.Content is just moved to its new owner, Leaf.Content. Disposing of content tokens does not erase anything, as the content was moved to the new owner and Token.Content == null.

AST is then transformed into a hierarchy of business entities specific to the application domain. AST leaves carry the values of properties of business-entities:

public class Employee : Entity
{
    public move SecureStr FirstName { get; set; }//<--maps to one AST leaf
    public move SecureStr LastName { get; set; }//<--maps to one AST leaf
    public move SecureStr Phone { get; set; }//<--maps to one AST leaf
    public move SecureStr Email { get; set; }//<--maps to one AST leaf
    public move SecureStr SocialSecurityNumber { get; set; }//<--maps to one AST leaf
    //...
    
    protected override void Dispose(bool disposing)
    {
        //...
    }
}

Once business entities are built, the AST is no longer used and the application disposes of it. There is no need to copy the content from AST leaves to fields of business entities. Instead, Leaf.Content is just moved to one of the fields of a business entity and that entity becomes the content owner.

When business entities are no longer needed, the application disposes of them. As they own all confidential content, they dispose of all SecureStr instances and thus actually erase the content in RAM. There are no other deep copies of content in RAM, as:

• The move keyword supports only exclusive ownership, and business entities were the last owners.
• SecureStr is a reference type and assigning it only copies references.
• If a field, property or method argument marked with move is neither disposed of nor moved, the compiler generates an error or warning. This prevents accidental errors like forgetting to dispose of a property.

Server architectures with data processing pipelines

A server application that needs to process requests is structured as a set of handlers, in the spirit of the chain of responsibilities pattern.

Each handler plays a specific role in processing. An incoming request is sometimes handled by several handlers to accomplish its goal.

However, it is not safe to process the same instance of request by multiple concurrently running handlers. Instead, a handler exclusively owns a request while processing it. When a handler is done with a request, it moves the request and its ownership to another handler or centralized dispatcher. Thread synchronization could be implemented similarly to one of the examples above.

Compare this to the Go's

Don't communicate by sharing memory; share memory by communicating

A similar Go server would organize handlers as goroutines and exchange requests between handlers through channels. Synchronization, when necessary, would be achieved using synchronous channel operations.

Simulating discrete material flows

The semantics of exclusive ownership backed by the move keyword is applicable to problems involving
physical movement of discrete material bodies between discrete places:

• Simulating manufacturing and assembly processes where discrete components move from one machine to another.
• Logistics and warehouse operations with goods moving between warehouse zones.
• Paper document flow between different employees and departments as documents undergo different phases of processing like editing/verification/approval/signing.

Conclusions

Open questions

This proposal is far from being complete or exhaustive.

Some open questions are:

• move/lease and overloading resolution

• collections of disposable resources and move/lease

• move/lease with Task<T> and await/async

• move/lease and System.ValueTuple

C++ and unique_ptr

Returning unique_ptr from a function in C++ clearly communicates that the function transfers a value and its ownership to the caller.

However, unique_ptr starts failing as soon as we want to allow someone else to use the contents of unique_ptr without transferring the ownership from the current owner. The sample copied from here shows the options we have in this case:

void borrower1(double*);

void borrower2(std::unique_ptr<double[]>*);

void borrower3(std::unique_ptr<double[]>&);

void uniqueness2()
{
    // p is created and owns a section of memory containing 42 numbers
    std::unique_ptr<double[]> p = std::make_unique<double[]>(42);

    // these are all okay but the first method is the most general
    // as it accepts any kind of pointer, not just unique_ptr
    borrower1(p.get());
    borrower2(&p);
    borrower3(p);

    // p dies, so the array is deleted automatically
}

All the options are obscure. Option 1 is the worst as it can mean absolutely anything in terms of ownership.

But the biggest problem is that unique_ptr and C++ do not offer even basic protection against incorrect use:

#include <memory>
#include <assert.h>

using namespace std;

//incorrect but compiles
int main()
{
    unique_ptr<int> p = make_unique<int>(1);
	
    assert(*p.get() == 1);

    auto p2 = move(p);

    int i = *p.get(); // access violation

    return 0;
}

C++ is helpless in preventing at compile-time even most trivial and obvious bugs, despite having such
powerful and relevant features as destructors, copy constructors, copy assignment operators, move constructors, static_assert, preprocessor macros.

These examples are provided to show that resource management cannot be expressed in terms of other language features and needs dedicated, built-in support from the compiler.

Value propositions

Thanks to the highly abstract nature of the proposed features, they can be applied to problems as low-level as managing system resources and as high-level as modeling some aspects of business logic and relations between business entities.

Abstract concepts that can be modeled in terms of this proposal include:

• Exclusive ownership, ownership transfer, permissions.
• Selecting or marking an entity among a group of similar entities with the intent to allow the entity to execute a privileged set of operations.
• Representing a particular state of an object that makes the object eligible for operations not allowed in other states.
• Expressing the constraint that some object is unique and cannot be copied.
• Responsibility to dispose of a resource; transferring that responsibility from one actor to another.
• Responsibility of the caller to keep a resource alive and available for at least as long as the callee is alive.
• Responsibility of the callee not to prolong the lifetime and use of a resource beyond the callee's own lifetime and use.
• Allowing non-owners to use a resource without transferring them the ownership.
• Simulating physical movement of discrete material bodies between discrete locations.

The move and lease keywords communicate developers' intentions to other humans, thus contributing to code clarity and readability.

At the same time, the keywords provide to the compiler so much missing metadata about resource "world lines" from instantiation to disposal and empower the compiler to perform rich static analysis of resource management.

Most resource management errors that currently can only be revealed at run-time using unit tests and load tests will instead be revealed at compile-time.

The ultimate goal of the proposed features is to allow authoring resource managing source code as
correct-by-design as possible.

[jnm2]

Estimated reading time: 70 minutes, 51 seconds. Contains 14173 words
(Given the subject matter, I'd say that's quite the underestimate 😆)

[wanton7]

Browsed through this proposal, but isn't this similar to #242 ?

[dmitrykm]

#242 is relatively new. No doubt they are similar.

[andrewjw1995]

Is it valid to move a variable into a closure, then execute the lambda multiple times?

move object x = new object();
var lambda = () => return move x;

// Both y and z will have ownership of x
move object y = lambda();
move object z = lambda();

[dmitrykm]

Moving a variable into a closure just by capturing the variable seems to be too tricky. Let’s say this is not allowed. But the following is allowed:

move object x = new object();
var lambda1 = () => return move x; //error: cannot move-return x because x is not owned by lambda1
var lambda2 = (move object arg) => return move arg;//ok

move object y = lambda2(move x);//y owns x 
move object z = lambda2(move x);//error

[sharwell]

@dmitrykm Why not just use ReferenceCountedDisposable<T> instead? This type is designed to challenge the idea that single-ownership is a value proposition, and already addresses the majority of items listed under the value propositions section of the proposal.