Who should call Dispose on IDisposable objects when passed into another object?

Is there any guidance or best practices around who should call Dispose() on disposable objects when they have been passed into another object's methods or constuctor?

Here's a couple of examples as to what I mean.

IDisposable object is passed into a method (Should it dispose of it once its done?):

public void DoStuff(IDisposable disposableObj)
{
    // Do something with disposableObj
    CalculateSomething(disposableObj)

    disposableObj.Dispose();
}

IDisposable object is passed into a method and a reference is kept (Should it dispose of it when MyClass is disposed?):

public class MyClass : IDisposable
{
    private IDisposable _disposableObj = null;

    public void DoStuff(IDisposable disposableObj)
    {
        _disposableObj = disposableObj;
    }

    public void Dispose()
    {
        _disposableObj.Dispose();
    }
}

I'm currently thinking that in the first example the caller of DoStuff() should dispose of the object as it probably created the object. But in the second example it feels like MyClass should dispose of the object as it keeps a reference to it. The problem with this is that the calling class might not know MyClass has kept a reference and therefore might decide to dispose of the object before MyClass has finished using it. Are there any standard rules for this sort of scenario? If there are, do they differ when the disposable object is being passed into a constructor?

Solution 1:

P.S.: I have posted a new answer (containing a simple set of rules who should call Dispose, and how to design an API that deals with IDisposable objects). While the present answer contains valuable ideas, I have come to believe that its main suggestion often won't work in practice: Hiding away IDisposable objects in "coarser-grained" objects often means that those need to become IDisposable themselves; so one ends up where one started, and the problem remains.

Is there any guidance or best practices around who should call Dispose() on disposable objects when they have been passed into another object's methods or constuctor?

Short answer:

Yes, there is much advice on this topic, and the best that I know of is Eric Evans' concept of Aggregates in Domain-Driven Design. (Simply put, the core idea as applied to IDisposable is this: Encapsulate the IDisposable in a coarser-grained component such that it is not seen by the outside and is never passed to the component consumer.)

Moreover, the idea that the creator of an IDisposable object should also be in charge of disposing it is too restrictive and often won't work in practice.

The rest of my answer goes into more detail on both points, in the same order. I'll finish off my answer with a few pointers to further material that is related to the same topic.

Longer answer — What this question is all about in broader terms:

Advice on this topic is usually not specific to IDisposable. Whenever people talk about object lifetimes and ownership, they are referring to the very same issue (but in more general terms).

Why does this topic hardly ever arise in the .NET ecosystem? Because .NET's runtime environment (the CLR) performs automatic garbage collection, which does all the work for you: If you no longer need an object, you can simply forget about it and the garbage collector will eventually reclaim its memory.

Why, then, does the question come up with IDisposable objects? Because IDisposable is all about the explicit, deterministic control of a (often sparse or expensive) resource's lifetime: IDisposable objects are supposed to be released as soon as they are no longer needed — and the garbage collector's indeterminate guarantee ("I'll eventually reclaim the memory used by you!") simply isn't good enough.

Your question, re-phrased in the broader terms of object lifetime and ownership:

Which object O should be responsible for ending the lifetime of a (disposable) object D, which also gets passed to objects X,Y,Z?

Let's establish a few assumptions:

• Calling D.Dispose() for an IDisposable object D basically ends its lifetime.

• Logically, an object's lifetime can only be ended once. (Never mind for the moment that this stands in opposition to the IDisposable protocol, which explicitly permits multiple calls to Dispose.)

• Therefore, for the sake of simplicity, exactly one object O should be responsible for disposing D. Let's call O the owner.

Now we get to the core of the issue: Neither the C# language, nor VB.NET provide a mechanism for enforcing ownership relationships between objects. So this turns into a design issue: All objects O,X,Y,Z that receive a reference to another object D must follow and adhere to a convention that regulates exactly who has ownership over D.

Simplify the problem with Aggregates!

The single best advice that I have found on this topic comes from Eric Evans' 2004 book, Domain-Driven Design. Let me cite from the book:

Say you were deleting a Person object from a database. Along with the person go a name, birth date, and a job description. But what about the address? There could be other people at the same address. If you delete the address, those Person objects will have references to a deleted object. If you leave it, you accumulate junk addresses in the database. Automatic garbage collection could eliminate the junk addresses, but that techncal fix, even if available in your database system, ignores a basic modeling issue. (p. 125)

See how this relates to your issue? The addresses from this example are the equivalent to your disposable objects, and the questions are the same: Who should delete them? Who "owns" them?

Evans goes on to suggest Aggregates as a solution to this design problem. From the book again:

An Aggregate is a cluster of associated objects that we treat as a unit for the purpose of data changes. Each Aggregate has a root and a boundary. The boundary defines what is inside the Aggregate. The root is a single, specific Entity contained in the Aggregate. The root is the only member of the Aggregate that outside objects are allowed to hold references to, although objects within the boundary may hold references to each other. (pp. 126-127)

The core message here is that you should restrict the passing-around of your IDisposable object to a strictly limited set ("aggregate") of other objects. Objects outside that aggregate boundary should never get a direct reference to your IDisposable. This greatly simplifies things, since you no longer need to worry whether the greatest part of all objects, namely those outside the aggregate, might Dispose your object. All you need to do is make sure that the objects inside the boundary all know who is responsible for disposing it. This should be an easy enough problem to solve, as you'd usually implement them together and take care to keep the aggregate boundaries reasonably "tight".

What about the suggestion that the creator of an IDisposable object should also dispose it?

This guideline sounds reasonable and there's an appealing symmetry to it, but just by itself, it often won't work in practice. Arguably it means the same as saying, "Never pass a reference to an IDisposable object to some other object", because as soon as you do that, you risk that the receiving object assumes its ownership and disposes it without your knowing.

Let's look at two prominent interface types from the .NET Base Class Library (BCL) that clearly violate this rule of thumb: IEnumerable<T> and IObservable<T>. Both are essentially factories that return IDisposable objects:

• IEnumerator<T> IEnumerable<T>.GetEnumerator()
  (Remember that IEnumerator<T> inherits from IDisposable.)

• IDisposable IObservable<T>.Subscribe(IObserver<T> observer)

In both cases, the caller is expected to dispose the returned object. Arguably, our guideline simply doesn't make sense in the case of object factories... unless, perhaps, we require that the requester (not its immediate creator) of the IDisposable releases it.

Incidentally, this example also demonstrates the limits of the aggregate solution outlined above: Both IEnumerable<T> and IObservable<T> are way too general in nature to ever be part of an aggregate. Aggregates are usually very domain-specific.

Further resources and ideas:

• In UML, "has a" relationships between objects can be modelled in two ways: As aggregation (empty diamond), or as composition (filled diamond). Composition differs from aggregation in that the contained/referred object's lifetime ends with that of the container/referrer. Your original question has implied aggregation ("transferable ownership"), while I've mostly steered towards solutions that use composition ("fixed ownership"). See the Wikipedia article on "Object composition".

• Autofac (a .NET IoC container) solves this problem in two ways: either by communicating, using a so-called relationship type, Owned<T>, who acquires ownership over an IDisposable; or through the concept of units of work, called lifetime scopes in Autofac.

• Regarding the latter, Nicholas Blumhardt, the creator of Autofac, has written "An Autofac Lifetime Primer", which includes a section "IDisposable and ownership". The whole article is an excellent treatise on ownership and lifetime issues in .NET. I recommend reading it, even to those not interested in Autofac.

• In C++, the Resource Acquisition Is Initialization (RAII) idiom (in general) and smart pointer types (in particular) help the programmer get object lifetime and ownership issues right. Unfortunately, these are not transferrable to .NET, because .NET lacks C++'s elegant support for deterministic object destruction.

• See also this answer to the question on Stack Overflow, "How to account for disparate implementation needs?", which (if I understand it correctly) follows a similar thought as my Aggregate-based answer: Building a coarse-grained component around the IDisposable such that it is completely contained (and hidden from the component consumer) within.

Solution 2:

A general rule is that if you created (or acquired ownership of) the object then it is your responsibility to dispose it. This means that if you receive a disposable object as a parameter in a method or constructor you usually should not dispose it.

Note that some classes in the .NET framework do dispose objects that they received as parameters. For example disposing a StreamReader also disposes the underlying Stream.

Solution 3:

This is a follow-up to my previous answer; see its initial remark to learn why I am posting another.

My previous answer got one thing right: Each IDisposable should have an exclusive "owner" who will be responsible for Dispose-ing of it exactly once. Managing IDisposable objects then becomes very comparable to managing memory in unmanaged code scenarios.

.NET's predecessor technology, the Component Object Model (COM), used the following protocol for memory management responsibilities between objects:

• "In-parameters must be allocated and freed by the caller.
• "Out-parameters must be allocated by the called; they are freed by the caller […].
• "In-out-parameters are initially allocated by the caller, and then freed and reallocated by the one called, if necessary. As is true for out parameters, the caller is responsible for freeing the final returned value."

(There are additional rules for error cases; see the page linked to above for details.)

If we were to adapt these guidelines for IDisposable, we could lay down the following…

Rules regarding IDisposable ownership:

1. When an IDisposable is passed into a method via a regular parameter, there is no transfer of ownership. The called method can use the IDisposable, but must not Dispose it (nor pass on ownership; see rule 4 below).
2. When an IDisposable is returned from a method via an out parameter or the return value, then ownership is transferred from the method to its caller. The caller will have to Dispose it (or pass on ownership over the IDisposable in the same way).
3. When an IDisposable is given to a method via a ref parameter, then ownership over it is transferred to that method. The method should copy the IDisposable into a local variable or object field and then set the ref parameter to null.

One possibly important rule follows from the above:

4. If you don't have ownership, you must not pass it on. That means, if you received an IDisposable object via a regular parameter, don't put the same object into a ref IDisposable parameter, nor expose it via a return value or out parameter.

Example:

sealed class LineReader : IDisposable
{
    public static LineReader Create(Stream stream)
    {
        return new LineReader(stream, ownsStream: false);
    }

    public static LineReader Create<TStream>(ref TStream stream) where TStream : Stream
    {
        try     { return new LineReader(stream, ownsStream: true); }
        finally { stream = null;                                   }
    }

    private LineReader(Stream stream, bool ownsStream)
    {
        this.stream = stream;
        this.ownsStream = ownsStream;
    }

    private Stream stream; // note: must not be exposed via property, because of rule (2)
    private bool ownsStream;

    public void Dispose()
    {
        if (ownsStream)
        {
            stream?.Dispose();
        }
    }

    public bool TryReadLine(out string line)
    {
        throw new NotImplementedException(); // read one text line from `stream` 
    }
}

This class has two static factory methods and thereby lets its client choose whether it wants to keep or pass on ownership:

• One accepts a Stream object via a regular parameter. This signals to the caller that ownership will not be taken over. Thus the caller needs to Dispose:

  using (var stream = File.OpenRead("Foo.txt"))
  using (var reader = LineReader.Create(stream))
  {
      string line;
      while (reader.TryReadLine(out line))
      {
          Console.WriteLine(line);
      }
  }
  

• One that accepts a Stream object via a ref parameter. This signals to the caller that ownership will be transferred, so the caller does not need to Dispose:

  var stream = File.OpenRead("Foo.txt");
  using (var reader = LineReader.Create(ref stream))
  {
      string line;
      while (reader.TryReadLine(out line))
      {
          Console.WriteLine(line);
      }
  }
  

  Interestingly, if stream were declared as a using variable: using (var stream = …), compilation would fail because using variables cannot be passed as ref parameters, so the C# compiler helps enforce our rules in this specific case.

Finally, note that File.OpenRead is an example for a method that returns a IDisposable object (namely, a Stream) via the return value, so ownership over the returned stream is transferred to the caller.

Disadvantage:

The main disadvantage to this pattern is that AFAIK, noone uses it (yet). So if you interact with any API that doesn't follow the above rules (for example, the .NET Framework Base Class Library) you still need to read the documentation to find out who has to call Dispose on IDisposable objects.

Solution 4:

In general, once you're dealing with a Disposable object, you're no longer in the ideal world of managed code where lifetime ownership is a moot point. Resultantly, you need to consider what object logically "owns", or is responsible for the lifetime of, your disposable object.

Generally, in the case of a disposable object that is just passed into a method, I would say no, the method should not dispose the object because it's very rare for one object to assume ownership of another object and then be done with it in the same method. The caller should be responsible for disposal in those cases.

There is no automatic answer that says "Yes, always dispose" or "No, never dispose" when talking about member data. Rather, you need to think about the objects in each specific case and ask yourself, "Is this object responsible for the lifetime of the disposable object?"

The rule of thumb is that the object responsible for creating a disposable owns it, and thus is responsible for disposing it later. This doesn't hold if there's an ownership transfer. For example:

public class Foo
{
    public MyClass BuildClass()
    {
        var dispObj = new DisposableObj();
        var retVal = new MyClass(dispObj);
        return retVal;
    }
}

Foo is clearly responsible for creating dispObj, but it's passing the ownership to the instance of MyClass.