Skip to content

Revised ManualResetEvent remarks #1739

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
rpetrusha merged 5 commits into from
Feb 5, 2019
Merged

Revised ManualResetEvent remarks #1739

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
4386a73
Revised ManualResetEvent remarks
pkulikov Jan 30, 2019
e387fb4
Updated links
pkulikov Jan 30, 2019
28a3699
Apply suggestions from code review
Feb 5, 2019
425e85a
Addressed feedback
pkulikov Feb 5, 2019
361ccef
Typo fix
pkulikov Feb 5, 2019
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
35 changes: 18 additions & 17 deletions xml/System.Threading/ManualResetEvent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,28 +34,29 @@
</Attribute>
</Attributes>
<Docs>
<summary>Notifies one or more waiting threads that an event has occurred. This class cannot be inherited.</summary>
<summary>Represents a thread synchronization event that, when signaled, must be reset manually. This class cannot be inherited.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
In the .NET Framework version 2.0, <xref:System.Threading.ManualResetEvent> derives from the new <xref:System.Threading.EventWaitHandle> class. A <xref:System.Threading.ManualResetEvent> is functionally equivalent to an <xref:System.Threading.EventWaitHandle> created with <xref:System.Threading.EventResetMode.ManualReset?displayProperty=nameWithType>.
> [!NOTE]
> Unlike the <xref:System.Threading.ManualResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events.
<xref:System.Threading.ManualResetEvent> allows threads to communicate with each other by signaling. Typically, this communication concerns a task which one thread must complete before other threads can proceed.
When a thread begins an activity that must complete before other threads proceed, it calls <xref:System.Threading.EventWaitHandle.Reset%2A> to put `ManualResetEvent` in the non-signaled state. This thread can be thought of as controlling the `ManualResetEvent`. Threads that call <xref:System.Threading.WaitHandle.WaitOne%2A> on the `ManualResetEvent` will block, awaiting the signal. When the controlling thread completes the activity, it calls <xref:System.Threading.EventWaitHandle.Set%2A> to signal that the waiting threads can proceed. All waiting threads are released.
Once it has been signaled, `ManualResetEvent` remains signaled until it is manually reset. That is, calls to `WaitOne` return immediately.
You use `ManualResetEvent`, <xref:System.Threading.AutoResetEvent>, and <xref:System.Threading.EventWaitHandle> for thread interaction (or thread signaling). For more information, see the [Thread interaction, or signaling](~/docs/standard/threading/overview-of-synchronization-primitives.md#thread-interaction-or-signaling) section of the [Overview of synchronization primitives](~/docs/standard/threading/overview-of-synchronization-primitives.md) article.
When a thread begins an activity that must complete before other threads proceed, it calls [ManualResetEvent.Reset](xref:System.Threading.EventWaitHandle.Reset%2A) to put `ManualResetEvent` in the non-signaled state. This thread can be thought of as controlling the `ManualResetEvent`. Threads that call [ManualResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne%2A) blocks, awaiting the signal. When the controlling thread completes the activity, it calls [ManualResetEvent.Set](xref:System.Threading.EventWaitHandle.Set%2A) to signal that the waiting threads can proceed. All waiting threads are released.
Once it has been signaled, `ManualResetEvent` remains signaled until it is manually reset. That is, calls to <xref:System.Threading.WaitHandle.WaitOne%2A> return immediately.
You can control the initial state of a `ManualResetEvent` by passing a Boolean value to the constructor, `true` if the initial state is signaled and `false` otherwise.
`ManualResetEvent` can also be used with the `static` <xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods.
`ManualResetEvent` can also be used with the `static`<xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods.
For more information about thread synchronization mechanisms, see [ManualResetEvent and ManualResetEventSlim](~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md) in the conceptual documentation.
Beginning with the .NET Framework version 2.0, <xref:System.Threading.ManualResetEvent> derives from the new <xref:System.Threading.EventWaitHandle> class. A <xref:System.Threading.ManualResetEvent> is functionally equivalent to an <xref:System.Threading.EventWaitHandle> created with <xref:System.Threading.EventResetMode.ManualReset?displayProperty=nameWithType>.
> [!NOTE]
> Unlike the <xref:System.Threading.ManualResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events.
Beginning with the .NET Framework version 4.0, the <xref:System.Threading.ManualResetEventSlim?displayProperty=nameWithType> class is a lightweight alternative to <xref:System.Threading.ManualResetEvent>.
## Examples
Expand All @@ -74,7 +75,7 @@
<threadsafe>This class is thread safe.</threadsafe>
<altmember cref="T:System.Threading.WaitHandle" />
<related type="Article" href="~/docs/standard/threading/index.md">Managed Threading</related>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">Manual Reset Event</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
<Members>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -125,7 +126,7 @@
</remarks>
<altmember cref="T:System.Threading.WaitHandle" />
<related type="Article" href="~/docs/standard/threading/index.md">Managed Threading</related>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Reset">
Expand Down
42 changes: 21 additions & 21 deletions xml/System.Threading/ManualResetEventSlim.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,15 +48,15 @@

Copy link

@rpetrusha rpetrusha Feb 4, 2019

Choose a reason for hiding this comment

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

Unrelated to your PR: The type description, "Provides a slimmed down version of ManualResetEvent", isn't helpful. Could you expand it by adding "to represent a thread synchronization event that, when signaled, must be reset manually."?


## Examples
The following example shows how to use a <xref:System.Threading.ManualResetEventSlim>. For more information about the use of `SpinCount` and other best practices concerning the use of this type, see [ManualResetEvent and ManualResetEventSlim](~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md).
The following example shows how to use a <xref:System.Threading.ManualResetEventSlim>.

[!code-csharp[System.Threading.ManualResetEventSlim#01](~/samples/snippets/csharp/VS_Snippets_CLR_System/system.threading.manualreseteventslim/cs/mres.cs#01)]
[!code-vb[System.Threading.ManualResetEventSlim#01](~/samples/snippets/visualbasic/VS_Snippets_CLR_System/system.threading.manualreseteventslim/vb/mres.vb#01)]

]]></format>
</remarks>
<threadsafe>All public and protected members of <see cref="T:System.Threading.ManualResetEventSlim" /> are thread-safe and may be used concurrently from multiple threads, with the exception of Dispose, which must only be used when all other operations on the <see cref="T:System.Threading.ManualResetEventSlim" /> have completed, and Reset, which should only be used when no other threads are accessing the event.</threadsafe>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
<Members>
<MemberGroup MemberName=".ctor">
Expand All @@ -68,7 +68,7 @@
</AssemblyInfo>
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Threading.ManualResetEventSlim" /> class.</summary>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</MemberGroup>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -98,7 +98,7 @@
<Docs>
<summary>Initializes a new instance of the <see cref="T:System.Threading.ManualResetEventSlim" /> class with an initial state of nonsignaled.</summary>
<remarks>To be added.</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -132,7 +132,7 @@
<param name="initialState">true to set the initial state signaled; false to set the initial state to nonsignaled.</param>
<summary>Initializes a new instance of the <see cref="T:System.Threading.ManualResetEventSlim" /> class with a Boolean value indicating whether to set the intial state to signaled.</summary>
<remarks>To be added.</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName=".ctor">
Expand Down Expand Up @@ -170,7 +170,7 @@
<remarks>To be added.</remarks>
<exception cref="T:System.ArgumentOutOfRangeException">
<paramref name="spinCount" /> is less than 0 or greater than the maximum allowed value.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<MemberGroup MemberName="Dispose">
Expand All @@ -182,7 +182,7 @@
</AssemblyInfo>
<Docs>
<summary>Releases resources used by the current instance of the <see cref="T:System.Threading.ManualResetEventSlim" /> class.</summary>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</MemberGroup>
<Member MemberName="Dispose">
Expand Down Expand Up @@ -231,7 +231,7 @@

]]></format>
</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Dispose">
Expand Down Expand Up @@ -275,7 +275,7 @@

]]></format>
</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="IsSet">
Expand Down Expand Up @@ -309,7 +309,7 @@
<summary>Gets whether the event is set.</summary>
<value>true if the event has is set; otherwise, false.</value>
<remarks>To be added.</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Reset">
Expand Down Expand Up @@ -351,7 +351,7 @@
]]></format>
</remarks>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Set">
Expand Down Expand Up @@ -385,7 +385,7 @@
<Docs>
<summary>Sets the state of the event to signaled, which allows one or more threads waiting on the event to proceed.</summary>
<remarks>To be added.</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="SpinCount">
Expand Down Expand Up @@ -419,7 +419,7 @@
<summary>Gets the number of spin waits that will occur before falling back to a kernel-based wait operation.</summary>
<value>Returns the number of spin waits that will occur before falling back to a kernel-based wait operation.</value>
<remarks>To be added.</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<MemberGroup MemberName="Wait">
Expand All @@ -431,7 +431,7 @@
</AssemblyInfo>
<Docs>
<summary>Blocks the current thread until the current <see cref="T:System.Threading.ManualResetEventSlim" /> is set.</summary>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</MemberGroup>
<Member MemberName="Wait">
Expand Down Expand Up @@ -474,7 +474,7 @@
</remarks>
<exception cref="T:System.InvalidOperationException">The maximum number of waiters has been exceeded.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Wait">
Expand Down Expand Up @@ -517,7 +517,7 @@
<paramref name="millisecondsTimeout" /> is a negative number other than -1, which represents an infinite time-out.</exception>
<exception cref="T:System.InvalidOperationException">The maximum number of waiters has been exceeded.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Wait">
Expand Down Expand Up @@ -564,7 +564,7 @@
<exception cref="T:System.OperationCanceledException">
<paramref name="cancellationToken" /> was canceled.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed or the <see cref="T:System.Threading.CancellationTokenSource" /> that created <paramref name="cancellationToken" /> has been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Wait">
Expand Down Expand Up @@ -611,7 +611,7 @@
The number of milliseconds in <paramref name="timeout" /> is greater than <see cref="F:System.Int32.MaxValue" />.</exception>
<exception cref="T:System.InvalidOperationException">The maximum number of waiters has been exceeded.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Wait">
Expand Down Expand Up @@ -657,7 +657,7 @@
<paramref name="millisecondsTimeout" /> is a negative number other than -1, which represents an infinite time-out.</exception>
<exception cref="T:System.InvalidOperationException">The maximum number of waiters has been exceeded.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed or the <see cref="T:System.Threading.CancellationTokenSource" /> that created <paramref name="cancellationToken" /> has been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Wait">
Expand Down Expand Up @@ -707,7 +707,7 @@
The number of milliseconds in <paramref name="timeout" /> is greater than <see cref="F:System.Int32.MaxValue" />.</exception>
<exception cref="T:System.InvalidOperationException">The maximum number of waiters has been exceeded.</exception>
<exception cref="T:System.ObjectDisposedException">The object has already been disposed or the <see cref="T:System.Threading.CancellationTokenSource" /> that created <paramref name="cancellationToken" /> has been disposed.</exception>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="WaitHandle">
Expand Down Expand Up @@ -748,7 +748,7 @@

]]></format>
</remarks>
<related type="Article" href="~/docs/standard/threading/manualresetevent-and-manualreseteventslim.md">ManualResetEvent and ManualResetEventSlim</related>
<related type="Article" href="~/docs/standard/threading/overview-of-synchronization-primitives.md">Overview of synchronization primitives</related>
</Docs>
</Member>
</Members>
Expand Down