<Type Name="IDisposable" FullName="System.IDisposable" FullNameSP="System_IDisposable" Maintainer="ecma">
  <TypeSignature Language="ILASM" Value=".class interface public abstract IDisposable" />
  <TypeSignature Language="C#" Value="public interface IDisposable" />
  <MemberOfLibrary>BCL</MemberOfLibrary>
  <AssemblyInfo>
    <AssemblyName>mscorlib</AssemblyName>
    <AssemblyPublicKey>[00 00 00 00 00 00 00 00 04 00 00 00 00 00 00 00 ]</AssemblyPublicKey>
    <AssemblyVersion>1.0.5000.0</AssemblyVersion>
    <AssemblyVersion>2.0.0.0</AssemblyVersion>
  </AssemblyInfo>
  <Docs>
    <summary>
      <para>Implemented by classes that require explicit control over resource cleanup.</para>
    </summary>
    <remarks>
      <para>Objects that need to free resources that cannot safely be reclaimed by the
      garbage collector implement the <see cref="T:System.IDisposable" /> interface. </para>
      <para>It is a version breaking change to add the <see cref="T:System.IDisposable" /> interface to an existing class, as it
   changes the semantics of the class. </para>
      <para>
        <block subset="none" type="note">
          <see cref="T:System.IDisposable" /> contains the <see cref="M:System.IDisposable.Dispose" /> method. The consumer of an object should 
call this method when the object is no longer needed. The <see cref="T:System.IDisposable" /> interface is generally provided for the
release of unmanaged resources that need to be reclaimed in some order or time
dependent manner. It is important to note that the actual release of these
resources happens at the first call to <see cref="M:System.IDisposable.Dispose" /> for
any given object that supports this interface. Programmers should take care
to pair the creation of objects that implement <see langword="IDisposable" /> with
at most one invocation of the <see langword="Dispose" /> method. Though it
is legal to invoke <see langword="Dispose" /> more than once, if this happens it
might indicate the presence of a bug since such an object is usually rendered
otherwise unusable after the first <see langword="Dispose" /> invocation. </block>
      </para>
    </remarks>
  </Docs>
  <Members>
    <Member MemberName="Dispose">
      <MemberSignature Language="ILASM" Value=".method public hidebysig virtual abstract void Dispose()" />
      <MemberSignature Language="C#" Value="public void Dispose ();" />
      <MemberType>Method</MemberType>
      <ReturnValue>
        <ReturnType>System.Void</ReturnType>
      </ReturnValue>
      <Parameters />
      <Docs>
        <summary>
          <para>Performs application-defined tasks associated with
      freeing or resetting resources.</para>
        </summary>
        <remarks>
          <block subset="none" type="note">
            <para>This method is, by convention, used for all tasks associated with freeing
         resources held by an object, or preparing an object for reuse. </para>
            <para>When implementing the <see cref="M:System.IDisposable.Dispose" /> method, objects should seek to ensure
      that all held resources are freed by propagating the call through the
      containment hierarchy. For example, if an object A allocates an object B, and B
      allocates an object C, then A's <see cref="M:System.IDisposable.Dispose" /> implementation should call
   <see cref="M:System.IDisposable.Dispose" /> on B,
      which should in turn call <see cref="M:System.IDisposable.Dispose" /> on C. Objects should also call the
   <see cref="M:System.IDisposable.Dispose" /> method
      of their base class if the base class implements <see cref="T:System.IDisposable" />.</para>
            <para>If an object's <see cref="M:System.IDisposable.Dispose" /> method is called more than once, the object should
   ignore all calls after the first one. The object should not throw an exception
   if its <see cref="M:System.IDisposable.Dispose" />
   method is called multiple times. <see cref="M:System.IDisposable.Dispose" /> can throw an exception if an error
   occurs because a resource has already been freed and
<see cref="M:System.IDisposable.Dispose" /> had 
   not been called previously. </para>
            <para>A resource type might use a particular convention to denote an allocated state
   versus a freed state. An example of this is stream classes, which are
   traditionally thought of as open or closed. Classes that have such conventions
   might choose to implement a public method with a customized name, which calls the
<see cref="M:System.IDisposable.Dispose" /> 
method. </para>
            <para>Because the <see cref="M:System.IDisposable.Dispose" /> method must be called explicitly, objects that implement
<see cref="T:System.IDisposable" /> 
should also implement a finalizer to handle freeing resources when
<see cref="M:System.IDisposable.Dispose" /> is not 
called. By default, the garbage collector will automatically call an object's
finalizer prior to reclaiming its memory. However, once the
<see cref="M:System.IDisposable.Dispose" /> method 
has been called, it is typically unnecessary and/or undesirable for the garbage
collector to call the disposed object's finalizer. To prevent automatic
finalization, <see cref="M:System.IDisposable.Dispose" /> implementations can call <see cref="M:System.GC.SuppressFinalize(System.Object)" />. For
additional information on implementing finalizers, see <see cref="T:System.GC" /> and <see cref="M:System.Object.Finalize" />.</para>
          </block>
        </remarks>
        <example>
          <para>Resource classes should follow the pattern illustrated by
      this example:</para>
          <code lang="C#">class ResourceWrapper : BaseType, IDisposable {
  // Pointer to a external resource.
  private int handle; 
  private OtherResource otherRes; //Other resource you use.
  private bool disposed = false;

  public ResourceWrapper () {
    handle = //Allocate on the unmanaged side.
    otherRes = new OtherResource (...);
  }
  // Free your own state.
  private void freeState () {
    if (!disposed) {
       CloseHandle (handle);
       dispose = true;
    }
  }

  // Free your own state, call dispose on all state you hold, 
  // and take yourself off the Finalization queue.
  public void Dispose () {
    freeState ();
    OtherRes.Dispose();
    // If base type implements dispose, call it.
    base.Dispose(); 
    GC.SuppressFinalize(this);  
  }

  // Free your own state (not other state you hold) 
  // and give your base class a chance to finalize. 
  ~ResourceWrapper (){
     freeState();
  }
}
   </code>
        </example>
      </Docs>
      <Excluded>0</Excluded>
      <AssemblyInfo>
        <AssemblyVersion>1.0.5000.0</AssemblyVersion>
        <AssemblyVersion>2.0.0.0</AssemblyVersion>
      </AssemblyInfo>
    </Member>
  </Members>
  <TypeExcluded>0</TypeExcluded>
  <Interfaces />
  <Attributes>
    <Attribute>
      <AttributeName>System.Runtime.InteropServices.ComVisible(true)</AttributeName>
    </Attribute>
  </Attributes>
</Type>
