Skip to content

Commit 412f1ea

Browse files
carlossanlopgewarren
carlossanlop
and
gewarren
authored
Port System.Threading new docs (#10162)
* System.Threading * System.Threading.Channels * System.Threading.Tasks * Apply suggestions from code review Co-authored-by: Genevieve Warren <[email protected]> --------- Co-authored-by: Genevieve Warren <[email protected]>
1 parent 1e4d3f1 commit 412f1ea

File tree

8 files changed

+222
-112
lines changed

8 files changed

+222
-112
lines changed

‎xml/System.Threading.Channels/Channel.xml

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -268,9 +268,11 @@
268268
<Parameters />
269269
<Docs>
270270
<typeparam name="T">To be added.</typeparam>
271-
<summary>To be added.</summary>
272-
<returns>To be added.</returns>
273-
<remarks>To be added.</remarks>
271+
<summary>Creates an unbounded prioritized channel usable by any number of readers and writers concurrently.</summary>
272+
<returns>The created channel.</returns>
273+
<remarks>
274+
<see cref="P:System.Collections.Generic.Comparer`1.Default" /> is used to determine priority of elements.
275+
The next item read from the channel will be the element available in the channel with the lowest priority value.</remarks>
274276
</Docs>
275277
</Member>
276278
<Member MemberName="CreateUnboundedPrioritized&lt;T&gt;">
@@ -302,11 +304,12 @@
302304
<Parameter Name="options" Type="System.Threading.Channels.UnboundedPrioritizedChannelOptions&lt;T&gt;" Index="0" FrameworkAlternate="net-8.0;net-9.0" />
303305
</Parameters>
304306
<Docs>
305-
<typeparam name="T">To be added.</typeparam>
306-
<param name="options">To be added.</param>
307-
<summary>To be added.</summary>
308-
<returns>To be added.</returns>
309-
<remarks>To be added.</remarks>
307+
<typeparam name="T">Specifies the type of data in the channel.</typeparam>
308+
<param name="options">Options that guide the behavior of the channel.</param>
309+
<summary>Creates an unbounded prioritized channel subject to the provided options.</summary>
310+
<returns>The created channel.</returns>
311+
<remarks>The <see cref="P:System.Threading.Channels.UnboundedPrioritizedChannelOptions`1.Comparer" /> of the supplied <paramref name="options" /> is used to determine priority of elements, or <see cref="P:System.Collections.Generic.Comparer`1.Default" /> if the provided comparer is <see langword="null" />.
312+
The next item read from the channel will be the element available in the channel with the lowest priority value.</remarks>
310313
</Docs>
311314
</Member>
312315
</Members>

‎xml/System.Threading.Channels/UnboundedPrioritizedChannelOptions`1.xml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525
<Interfaces />
2626
<Docs>
2727
<typeparam name="T">To be added.</typeparam>
28-
<summary>To be added.</summary>
28+
<summary>Provides options that control the behavior of instances created by <see cref="M:Channel.CreateUnboundedPrioritized" />.</summary>
2929
<remarks>To be added.</remarks>
3030
</Docs>
3131
<Members>
@@ -68,7 +68,7 @@
6868
<ReturnType>System.Collections.Generic.IComparer&lt;T&gt;</ReturnType>
6969
</ReturnValue>
7070
<Docs>
71-
<summary>To be added.</summary>
71+
<summary>Gets or sets the comparer used by the channel to prioritize elements.</summary>
7272
<value>To be added.</value>
7373
<remarks>To be added.</remarks>
7474
</Docs>

‎xml/System.Threading.Tasks/Task.xml

Lines changed: 76 additions & 25 deletions
Large diffs are not rendered by default.

‎xml/System.Threading.Tasks/TaskCompletionSource.xml

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -302,9 +302,16 @@ The <xref:System.Threading.Tasks.Task> created by this instance and accessible t
302302
<Parameter Name="completedTask" Type="System.Threading.Tasks.Task" Index="0" FrameworkAlternate="net-9.0" />
303303
</Parameters>
304304
<Docs>
305-
<param name="completedTask">To be added.</param>
306-
<summary>To be added.</summary>
307-
<remarks>To be added.</remarks>
305+
<param name="completedTask">The completed task whose completion status (including exception or cancellation information) should be copied to the underlying task.</param>
306+
<summary>Transitions the underlying <see cref="T:System.Threading.Tasks.Task`1" /> into the same completion state as the specified <paramref name="completedTask" />.</summary>
307+
<remarks>This operation will return <see langword="false" /> if the <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
308+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</remarks>
309+
<exception cref="T:System.ArgumentNullException">
310+
<paramref name="completedTask" /> is <see langword="null" />.</exception>
311+
<exception cref="T:System.ArgumentException">
312+
<paramref name="completedTask" /> is not completed.</exception>
313+
<exception cref="T:System.InvalidOperationException">The underlying <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
314+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</exception>
308315
</Docs>
309316
</Member>
310317
<Member MemberName="SetResult">
@@ -545,10 +552,16 @@ This operation will return `false` if the <xref:System.Threading.Tasks.Task> is
545552
<Parameter Name="completedTask" Type="System.Threading.Tasks.Task" Index="0" FrameworkAlternate="net-9.0" />
546553
</Parameters>
547554
<Docs>
548-
<param name="completedTask">To be added.</param>
549-
<summary>To be added.</summary>
550-
<returns>To be added.</returns>
551-
<remarks>To be added.</remarks>
555+
<param name="completedTask">The completed task whose completion status (including exception or cancellation information) should be copied to the underlying task.</param>
556+
<summary>Attempts to transition the underlying <see cref="T:System.Threading.Tasks.Task`1" /> into the same completion state as the specified <paramref name="completedTask" />.</summary>
557+
<returns>
558+
<see langword="true" /> if the operation was successful; otherwise, <see langword="false" />.</returns>
559+
<remarks>This operation will return <see langword="false" /> if the <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
560+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</remarks>
561+
<exception cref="T:System.ArgumentNullException">
562+
<paramref name="completedTask" /> is <see langword="null" />.</exception>
563+
<exception cref="T:System.ArgumentException">
564+
<paramref name="completedTask" /> is not completed.</exception>
552565
</Docs>
553566
</Member>
554567
<Member MemberName="TrySetResult">

‎xml/System.Threading.Tasks/TaskCompletionSource`1.xml

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -535,9 +535,16 @@
535535
<Parameter Name="completedTask" Type="System.Threading.Tasks.Task&lt;TResult&gt;" Index="0" FrameworkAlternate="net-9.0" />
536536
</Parameters>
537537
<Docs>
538-
<param name="completedTask">To be added.</param>
539-
<summary>To be added.</summary>
540-
<remarks>To be added.</remarks>
538+
<param name="completedTask">The completed task whose completion status (including result, exception, or cancellation information) should be copied to the underlying task.</param>
539+
<summary>Transitions the underlying <see cref="T:System.Threading.Tasks.Task`1" /> into the same completion state as the specified <paramref name="completedTask" />.</summary>
540+
<remarks>This operation will return <see langword="false" /> if the <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
541+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</remarks>
542+
<exception cref="T:System.ArgumentNullException">
543+
<paramref name="completedTask" /> is <see langword="null" />.</exception>
544+
<exception cref="T:System.ArgumentException">
545+
<paramref name="completedTask" /> is not completed.</exception>
546+
<exception cref="T:System.InvalidOperationException">The underlying <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
547+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</exception>
541548
</Docs>
542549
</Member>
543550
<Member MemberName="SetResult">
@@ -937,10 +944,16 @@
937944
<Parameter Name="completedTask" Type="System.Threading.Tasks.Task&lt;TResult&gt;" Index="0" FrameworkAlternate="net-9.0" />
938945
</Parameters>
939946
<Docs>
940-
<param name="completedTask">To be added.</param>
941-
<summary>To be added.</summary>
942-
<returns>To be added.</returns>
943-
<remarks>To be added.</remarks>
947+
<param name="completedTask">The completed task whose completion status (including result, exception, or cancellation information) should be copied to the underlying task.</param>
948+
<summary>Attempts to transition the underlying <see cref="T:System.Threading.Tasks.Task`1" /> into the same completion state as the specified <paramref name="completedTask" />.</summary>
949+
<returns>
950+
<see langword="true" /> if the operation was successful; otherwise, <see langword="false" />.</returns>
951+
<remarks>This operation will return <see langword="false" /> if the <see cref="T:System.Threading.Tasks.Task`1" /> is already in one of the three final states:
952+
<see cref="F:System.Threading.Tasks.TaskStatus.RanToCompletion" />, <see cref="F:System.Threading.Tasks.TaskStatus.Faulted" />, or <see cref="F:System.Threading.Tasks.TaskStatus.Canceled" />.</remarks>
953+
<exception cref="T:System.ArgumentNullException">
954+
<paramref name="completedTask" /> is <see langword="null" />.</exception>
955+
<exception cref="T:System.ArgumentException">
956+
<paramref name="completedTask" /> is not completed.</exception>
944957
</Docs>
945958
</Member>
946959
<Member MemberName="TrySetResult">

‎xml/System.Threading.Tasks/TimeProviderTaskExtensions.xml

Lines changed: 44 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,9 @@
2424
</Attribute>
2525
</Attributes>
2626
<Docs>
27-
<summary>To be added.</summary>
28-
<remarks>To be added.</remarks>
27+
<summary>Provides extensions methods for <see cref="T:System.Threading.Tasks.Task" /> operations with <see cref="T:System.TimeProvider" />.</summary>
28+
<remarks>The Microsoft.Bcl.TimeProvider library interfaces are intended solely for use in building against pre-.NET 8 surface area.
29+
If your code is being built against .NET 8 or later, then don't use this library.</remarks>
2930
</Docs>
3031
<Members>
3132
<Member MemberName="CreateCancellationTokenSource">
@@ -48,11 +49,19 @@
4849
<Parameter Name="delay" Type="System.TimeSpan" />
4950
</Parameters>
5051
<Docs>
51-
<param name="timeProvider">To be added.</param>
52-
<param name="delay">To be added.</param>
53-
<summary>To be added.</summary>
54-
<returns>To be added.</returns>
55-
<remarks>To be added.</remarks>
52+
<param name="timeProvider">The <see cref="T:System.TimeProvider" /> with which to interpret the <paramref name="delay" />.</param>
53+
<param name="delay">The time interval to wait before canceling this <see cref="T:System.Threading.CancellationTokenSource" />.</param>
54+
<summary>Initializes a new instance of the <see cref="T:System.Threading.CancellationTokenSource" /> class that will be canceled after the specified <see cref="T:System.TimeSpan" />.</summary>
55+
<returns>
56+
<see cref="T:System.Threading.CancellationTokenSource" /> that will be canceled after the specified <paramref name="delay" />.</returns>
57+
<remarks>
58+
<para> The countdown for the delay starts during the call to the constructor. When the delay expires, the constructed <see cref="T:System.Threading.CancellationTokenSource" /> is canceled if it has not been canceled already.
59+
</para>
60+
<para> If running on .NET versions earlier than .NET 8, there is a constraint when invoking <see cref="M:System.Threading.CancellationTokenSource.CancelAfter(System.TimeSpan)" /> on the resultant object.
61+
This action will not terminate the initial timer indicated by <paramref name="delay" />. However, this restriction does not apply on .NET 8 and later versions.
62+
</para>
63+
</remarks>
64+
<exception cref="T:System.ArgumentOutOfRangeException">The <paramref name="delay" /> is negative and not equal to <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />, or is greater than the maximum allowed timer duration.</exception>
5665
</Docs>
5766
</Member>
5867
<Member MemberName="Delay">
@@ -75,12 +84,15 @@
7584
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
7685
</Parameters>
7786
<Docs>
78-
<param name="timeProvider">To be added.</param>
79-
<param name="delay">To be added.</param>
80-
<param name="cancellationToken">To be added.</param>
81-
<summary>To be added.</summary>
82-
<returns>To be added.</returns>
87+
<param name="timeProvider">The <see cref="T:System.TimeProvider" /> with which to interpret <paramref name="delay" />.</param>
88+
<param name="delay">The <see cref="T:System.TimeSpan" /> to wait before completing the returned task, or <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" /> to wait indefinitely.</param>
89+
<param name="cancellationToken">A cancellation token to observe while waiting for the task to complete.</param>
90+
<summary>Creates a task that completes after a specified time interval.</summary>
91+
<returns>A task that represents the time delay.</returns>
8392
<remarks>To be added.</remarks>
93+
<exception cref="T:System.ArgumentNullException">The <paramref name="timeProvider" /> argument is <see langword="null" />.</exception>
94+
<exception cref="T:System.ArgumentOutOfRangeException">
95+
<paramref name="delay" /> represents a negative time interval other than <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</exception>
8496
</Docs>
8597
</Member>
8698
<Member MemberName="WaitAsync">
@@ -104,13 +116,17 @@
104116
<Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" />
105117
</Parameters>
106118
<Docs>
107-
<param name="task">To be added.</param>
108-
<param name="timeout">To be added.</param>
109-
<param name="timeProvider">To be added.</param>
110-
<param name="cancellationToken">To be added.</param>
111-
<summary>To be added.</summary>
112-
<returns>To be added.</returns>
119+
<param name="task">The task for which to wait on until completion.</param>
120+
<param name="timeout">The timeout after which the <see cref="T:System.Threading.Tasks.Task" /> should be faulted with a <see cref="T:System.TimeoutException" /> if it hasn't otherwise completed.</param>
121+
<param name="timeProvider">The <see cref="T:System.TimeProvider" /> with which to interpret <paramref name="timeout" />.</param>
122+
<param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> to monitor for a cancellation request.</param>
123+
<summary>Gets a <see cref="T:System.Threading.Tasks.Task" /> that will complete when this <see cref="T:System.Threading.Tasks.Task" /> completes, when the specified timeout expires, or when the specified <see cref="T:System.Threading.CancellationToken" /> has cancellation requested.</summary>
124+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> representing the asynchronous wait. It may or may not be the same instance as the current instance.</returns>
113125
<remarks>To be added.</remarks>
126+
<exception cref="T:System.ArgumentNullException">
127+
<paramref name="task" /> or <paramref name="timeProvider" /> is <see langword="null" />.</exception>
128+
<exception cref="T:System.ArgumentOutOfRangeException">
129+
<paramref name="timeout" /> represents a negative time interval other than <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</exception>
114130
</Docs>
115131
</Member>
116132
<Member MemberName="WaitAsync&lt;TResult&gt;">
@@ -145,13 +161,17 @@
145161
</Parameters>
146162
<Docs>
147163
<typeparam name="TResult">To be added.</typeparam>
148-
<param name="task">To be added.</param>
149-
<param name="timeout">To be added.</param>
150-
<param name="timeProvider">To be added.</param>
151-
<param name="cancellationToken">To be added.</param>
152-
<summary>To be added.</summary>
153-
<returns>To be added.</returns>
164+
<param name="task">The task for which to wait on until completion.</param>
165+
<param name="timeout">The timeout after which the <see cref="T:System.Threading.Tasks.Task" /> should be faulted with a <see cref="T:System.TimeoutException" /> if it hasn't otherwise completed.</param>
166+
<param name="timeProvider">The <see cref="T:System.TimeProvider" /> with which to interpret <paramref name="timeout" />.</param>
167+
<param name="cancellationToken">The <see cref="T:System.Threading.CancellationToken" /> to monitor for a cancellation request.</param>
168+
<summary>Gets a <see cref="T:System.Threading.Tasks.Task" /> that will complete when this <see cref="T:System.Threading.Tasks.Task" /> completes, when the specified timeout expires, or when the specified <see cref="T:System.Threading.CancellationToken" /> has cancellation requested.</summary>
169+
<returns>The <see cref="T:System.Threading.Tasks.Task" /> representing the asynchronous wait. It may or may not be the same instance as the current instance.</returns>
154170
<remarks>To be added.</remarks>
171+
<exception cref="T:System.ArgumentNullException">
172+
<paramref name="task" /> or <paramref name="timeProvider" /> is <see langword="null" />.</exception>
173+
<exception cref="T:System.ArgumentOutOfRangeException">
174+
<paramref name="timeout" /> represents a negative time interval other than <see cref="F:System.Threading.Timeout.InfiniteTimeSpan" />.</exception>
155175
</Docs>
156176
</Member>
157177
</Members>

‎xml/System.Threading/CancellationTokenSource.xml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -698,9 +698,9 @@
698698
</Parameter>
699699
</Parameters>
700700
<Docs>
701-
<param name="tokens">To be added.</param>
702-
<summary>To be added.</summary>
703-
<returns>To be added.</returns>
701+
<param name="tokens">The <see cref="T:System.Threading.CancellationToken">CancellationToken</see> instances to observe.</param>
702+
<summary>Creates a <see cref="T:System.Threading.CancellationTokenSource" /> that will be in the canceled state when any of the source tokens are in the canceled state.</summary>
703+
<returns>A <see cref="T:System.Threading.CancellationTokenSource" /> that is linked to the source tokens.</returns>
704704
<remarks>To be added.</remarks>
705705
</Docs>
706706
</Member>

0 commit comments

Comments
 (0)