1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
<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>
|
