Skip to content

Improve System.GC documentation #3559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 25, 2019
Merged

Improve System.GC documentation #3559

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 27 additions & 29 deletions xml/System/GC.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@
</remarks>
<altmember cref="T:System.Runtime.GCSettings" />
<related type="Article" href="~/docs/standard/garbage-collection/index.md">Garbage Collection</related>
<related type="Article" href="https://msdn.microsoft.com/library/67c5a20d-1be1-4ea7-8a9a-92b0b08658d2">Fundamentals of Garbage Collection</related>
<related type="Article" href="~/docs/standard/garbage-collection/fundamentals.md">Fundamentals of Garbage Collection</related>
</Docs>
<Members>
<Member MemberName="AddMemoryPressure">
Expand Down Expand Up @@ -218,7 +218,7 @@
<exception cref="T:System.InvalidOperationException">This member is not available when concurrent garbage collection is enabled. See the [&lt;gcConcurrent&gt;](~/docs/framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) runtime setting for information about how to disable concurrent garbage collection.</exception>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">requires full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'll go ahead and merge as-is.

<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
</Docs>
</Member>
<MemberGroup MemberName="Collect">
Expand Down Expand Up @@ -298,7 +298,7 @@

]]></format>
</remarks>
<related type="Article" href="https://msdn.microsoft.com/library/019008fe-4708-4e65-bebf-04fd9941e149">Induced Collections</related>
<related type="Article" href="~/docs/standard/garbage-collection/induced.md">Induced Collections</related>
</Docs>
</Member>
<Member MemberName="Collect">
Expand Down Expand Up @@ -364,7 +364,7 @@
</remarks>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="generation" /> is not valid.</exception>
<related type="Article" href="https://msdn.microsoft.com/library/019008fe-4708-4e65-bebf-04fd9941e149">Induced Collections</related>
<related type="Article" href="~/docs/standard/garbage-collection/induced.md">Induced Collections</related>
</Docs>
</Member>
<Member MemberName="Collect">
Expand Down Expand Up @@ -441,7 +441,7 @@
-or-

<paramref name="mode" /> is not one of the <see cref="T:System.GCCollectionMode" /> values.</exception>
<related type="Article" href="https://msdn.microsoft.com/library/019008fe-4708-4e65-bebf-04fd9941e149">Induced Collections</related>
<related type="Article" href="~/docs/standard/garbage-collection/induced.md">Induced Collections</related>
</Docs>
</Member>
<Member MemberName="Collect">
Expand Down Expand Up @@ -699,7 +699,7 @@
A memory allocation exceeded the amount specified in the call to the <see cref="M:System.GC.TryStartNoGCRegion(System.Int64)" /> method.</exception>
<altmember cref="M:System.GC.TryStartNoGCRegion(System.Int64)" />
<altmember cref="P:System.Runtime.GCSettings.LatencyMode" />
<related type="Article" href="https://msdn.microsoft.com/library/96278bb7-6eab-4612-8594-ceebfc887d81">Latency Modes</related>
<related type="Article" href="~/docs/standard/garbage-collection/latency.md">Latency Modes</related>
</Docs>
</Member>
<Member MemberName="GetAllocatedBytesForCurrentThread">
Expand Down Expand Up @@ -1118,22 +1118,20 @@ This method is most useful in monitoring scenarios for measuring the difference

If object aging is implemented, the <xref:System.GC.MaxGeneration%2A> property returns the maximum generation number used by the system; otherwise, this property returns zero.


For this implementation, the value returned by the <xref:System.GC.MaxGeneration> property is guaranteed to remain constant for the lifetime of an executing application.

Use the <xref:System.GC.MaxGeneration> property to determine the maximum value you can specify when calling the <xref:System.GC.Collect%28System.Int32%29> method that takes a generation parameter.


## Examples
The following example demonstrates how to use the MaxGeneration property to display the largest generation number currently in use.
The following example demonstrates how to use the <xref:System.GC.MaxGeneration> property to display the largest generation number currently in use.

[!code-cpp[System.GC.Collect Int Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.gc.collect int example/CPP/class1.cpp#1)]
[!code-csharp[System.GC.Collect Int Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.gc.collect int example/CS/class1.cs#1)]
[!code-vb[System.GC.Collect Int Example#1](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.gc.collect int example/VB/class1.vb#1)]

]]></format>
</remarks>
<block subset="none" type="overrides">
<para>For this implementation, the value returned by the <see cref="P:System.GC.MaxGeneration" /> property is guaranteed to remain constant for the lifetime of an executing application.

Use the <see cref="P:System.GC.MaxGeneration" /> property to determine the maximum value you can specify when calling the <see cref="M:System.GC.Collect(System.Int32)" /> method that takes a generation parameter.</para>
</block>
</remarks>
<altmember cref="M:System.GC.GetGeneration(System.Object)" />
</Docs>
</Member>
Expand Down Expand Up @@ -1220,7 +1218,7 @@ This method is most useful in monitoring scenarios for measuring the difference
<paramref name="maxGenerationThreshold" /> or <paramref name="largeObjectHeapThreshold" /> is not between 1 and 99.</exception>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
<exception cref="T:System.InvalidOperationException">This member is not available when concurrent garbage collection is enabled. See the &lt;gcConcurrent&gt; runtime setting for information about how to disable concurrent garbage collection.</exception>
</Docs>
</Member>
Expand Down Expand Up @@ -1349,7 +1347,7 @@ This method is most useful in monitoring scenarios for measuring the difference


## Examples
The following example demonstrates how to use the ReRegisterForFinalize method to finalize an object a second time after garbage collection.
The following example demonstrates how to use the <xref:System.GC.ReRegisterForFinalize%2A> method to finalize an object a second time after garbage collection.

[!code-cpp[System.GC.ReregisterForFinalize Example#1](~/samples/snippets/cpp/VS_Snippets_CLR_System/system.GC.ReRegisterForFinalize Example/CPP/class1.cpp#1)]
[!code-csharp[System.GC.ReregisterForFinalize Example#1](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.GC.ReRegisterForFinalize Example/CS/class1.cs#1)]
Expand Down Expand Up @@ -1435,7 +1433,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="obj" /> is <see langword="null" />.</exception>
<altmember cref="M:System.GC.ReRegisterForFinalize(System.Object)" />
<altmember cref="M:System.Object.Finalize" />
<related type="Article" href="https://msdn.microsoft.com/library/31a6c13b-d6a2-492b-9a9f-e5238c983bcb">Dispose Pattern</related>
<related type="Article" href="~/docs/standard/garbage-collection/implementing-dispose.md">Dispose Pattern</related>
</Docs>
</Member>
<MemberGroup MemberName="TryStartNoGCRegion">
Expand Down Expand Up @@ -1517,8 +1515,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="totalSize" /> exceeds the ephemeral segment size.</exception>
<exception cref="T:System.InvalidOperationException">The process is already in no GC region latency mode.</exception>
<altmember cref="M:System.GC.EndNoGCRegion" />
<related type="Article" href="https://msdn.microsoft.com/library/67c5a20d-1be1-4ea7-8a9a-92b0b08658d2">Fundamentals of Garbage Collection</related>
<related type="Article" href="https://msdn.microsoft.com/library/96278bb7-6eab-4612-8594-ceebfc887d81">Latency Modes</related>
<related type="Article" href="~/docs/standard/garbage-collection/fundamentals.md">Fundamentals of Garbage Collection</related>
<related type="Article" href="~/docs/standard/garbage-collection/latency.md">Latency Modes</related>
</Docs>
</Member>
<Member MemberName="TryStartNoGCRegion">
Expand Down Expand Up @@ -1584,8 +1582,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="totalSize" /> exceeds the ephemeral segment size.</exception>
<exception cref="T:System.InvalidOperationException">The process is already in no GC region latency mode.</exception>
<altmember cref="M:System.GC.EndNoGCRegion" />
<related type="Article" href="https://msdn.microsoft.com/library/67c5a20d-1be1-4ea7-8a9a-92b0b08658d2">Fundamentals of Garbage Collection</related>
<related type="Article" href="https://msdn.microsoft.com/library/96278bb7-6eab-4612-8594-ceebfc887d81">Latency Modes</related>
<related type="Article" href="~/docs/standard/garbage-collection/fundamentals.md">Fundamentals of Garbage Collection</related>
<related type="Article" href="~/docs/standard/garbage-collection/latency.md">Latency Modes</related>
</Docs>
</Member>
<Member MemberName="TryStartNoGCRegion">
Expand Down Expand Up @@ -1648,8 +1646,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="totalSize" /> - <paramref name="lohSize" /> exceeds the ephemeral segment size.</exception>
<exception cref="T:System.InvalidOperationException">The process is already in no GC region latency mode.</exception>
<altmember cref="M:System.GC.EndNoGCRegion" />
<related type="Article" href="https://msdn.microsoft.com/library/67c5a20d-1be1-4ea7-8a9a-92b0b08658d2">Fundamentals of Garbage Collection</related>
<related type="Article" href="https://msdn.microsoft.com/library/96278bb7-6eab-4612-8594-ceebfc887d81">Latency Modes</related>
<related type="Article" href="~/docs/standard/garbage-collection/fundamentals.md">Fundamentals of Garbage Collection</related>
<related type="Article" href="~/docs/standard/garbage-collection/latency.md">Latency Modes</related>
</Docs>
</Member>
<Member MemberName="TryStartNoGCRegion">
Expand Down Expand Up @@ -1717,8 +1715,8 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="totalSize" /> - <paramref name="lohSize" /> exceeds the ephemeral segment size.</exception>
<exception cref="T:System.InvalidOperationException">The process is already in no GC region latency mode.</exception>
<altmember cref="M:System.GC.EndNoGCRegion" />
<related type="Article" href="https://msdn.microsoft.com/library/67c5a20d-1be1-4ea7-8a9a-92b0b08658d2">Fundamentals of Garbage Collection</related>
<related type="Article" href="https://msdn.microsoft.com/library/96278bb7-6eab-4612-8594-ceebfc887d81">Latency Modes</related>
<related type="Article" href="~/docs/standard/garbage-collection/fundamentals.md">Fundamentals of Garbage Collection</related>
<related type="Article" href="~/docs/standard/garbage-collection/latency.md">Latency Modes</related>
</Docs>
</Member>
<MemberGroup MemberName="WaitForFullGCApproach">
Expand Down Expand Up @@ -1792,7 +1790,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
</remarks>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
</Docs>
</Member>
<Member MemberName="WaitForFullGCApproach">
Expand Down Expand Up @@ -1854,7 +1852,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="millisecondsTimeout" /> must be either non-negative or less than or equal to <see cref="F:System.Int32.MaxValue" /> or -1.</exception>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
</Docs>
</Member>
<MemberGroup MemberName="WaitForFullGCComplete">
Expand Down Expand Up @@ -1928,7 +1926,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
</remarks>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
</Docs>
</Member>
<Member MemberName="WaitForFullGCComplete">
Expand Down Expand Up @@ -1990,7 +1988,7 @@ If `obj` does not have a finalizer or the GC has already signaled the finalizer
<paramref name="millisecondsTimeout" /> must be either non-negative or less than or equal to <see cref="F:System.Int32.MaxValue" /> or -1.</exception>
<permission cref="F:System.Security.Permissions.SecurityAction.LinkDemand">for full trust for the immediate caller. This member cannot be used by partially trusted code.</permission>
<permission cref="T:System.Security.SecurityCriticalAttribute">requires full trust for the immediate caller. This member cannot be used by partially trusted or transparent code.</permission>
<related type="Article" href="https://msdn.microsoft.com/library/e12d8e74-31e3-4035-a87d-f3e66f0a9b89">Garbage Collection Notifications</related>
<related type="Article" href="~/docs/standard/garbage-collection/notifications.md">Garbage Collection Notifications</related>
</Docs>
</Member>
<Member MemberName="WaitForPendingFinalizers">
Expand Down