Skip to content

Follow up editing for AutoResetEvent #9725

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 2 commits into from
Apr 2, 2024
Merged

Follow up editing for AutoResetEvent #9725

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f80edc
follow up editing
gewarren Mar 14, 2024
32daa0a
Update xml/System.Threading/AutoResetEvent.xml
gewarren Apr 2, 2024
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
103 changes: 51 additions & 52 deletions xml/System.Threading/AutoResetEvent.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,45 +55,43 @@
</Attribute>
</Attributes>
<Docs>
<summary>Represents a thread synchronization event that, when signaled, releases one single waiting thread, and the event resets automatically. If no thread is waiting, the next thread that is set to the waiting state is immediately released, and the event resets automatically. This class cannot be inherited.</summary>
<summary>Represents a thread synchronization event that, when signaled, releases one single waiting thread and then resets automatically. This class cannot be inherited.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
You use `AutoResetEvent`, <xref:System.Threading.ManualResetEvent>, and <xref:System.Threading.EventWaitHandle> for thread interaction (or thread signaling). For more information, see the [Thread interaction, or signaling](/dotnet/standard/threading/overview-of-synchronization-primitives#thread-interaction-or-signaling) section of the [Overview of synchronization primitives](/dotnet/standard/threading/overview-of-synchronization-primitives) article.

> [!IMPORTANT]
> This type implements the <xref:System.IDisposable> interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its <xref:System.IDisposable.Dispose%2A> method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section in the <xref:System.IDisposable> interface topic.

A thread waits for a signal by calling [AutoResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne%2A). If the `AutoResetEvent` is in the non-signaled state, the thread blocks until [AutoResetEvent.Set](xref:System.Threading.EventWaitHandle.Set%2A) is called.

Calling `Set` signals `AutoResetEvent` to release a waiting thread. `AutoResetEvent` remains signaled until a single waiting thread is released, and then automatically returns to the non-signaled state. If no threads are waiting, the state remains signaled indefinitely.

If a thread calls <xref:System.Threading.WaitHandle.WaitOne%2A> while the <xref:System.Threading.AutoResetEvent> is in the signaled state, the thread does not block. The <xref:System.Threading.AutoResetEvent> releases the thread immediately and returns to the non-signaled state.

<format type="text/markdown"><![CDATA[

## Remarks

You use `AutoResetEvent`, <xref:System.Threading.ManualResetEvent>, and <xref:System.Threading.EventWaitHandle> for thread interaction (or thread signaling). For more information, see [Thread interaction](/dotnet/standard/threading/overview-of-synchronization-primitives#thread-interaction-or-signaling).

A thread waits for a signal by calling [AutoResetEvent.WaitOne](xref:System.Threading.WaitHandle.WaitOne%2A). If the `AutoResetEvent` is in the non-signaled state, the thread blocks until [AutoResetEvent.Set](xref:System.Threading.EventWaitHandle.Set%2A) is called. Calling `Set` signals `AutoResetEvent` to release a waiting thread. `AutoResetEvent` remains signaled until `Reset` is called or a single waiting thread is released, at which time it automatically returns to the non-signaled state.

If no threads are waiting when the `AutoResetEvent` goes into a signaled state, the state remains signaled until a thread observes the signal (by calling <xref:System.Threading.WaitHandle.WaitOne%2A>). That thread does not block: the <xref:System.Threading.AutoResetEvent> releases the thread immediately and returns to the non-signaled state.

> [!IMPORTANT]
> There is no guarantee that every call to the <xref:System.Threading.EventWaitHandle.Set%2A> method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It's as if the second call did not happen. Also, if <xref:System.Threading.EventWaitHandle.Set%2A> is called when there are no threads waiting and the <xref:System.Threading.AutoResetEvent> is already signaled, the call has no effect.
You can control the initial state of an `AutoResetEvent` by passing a Boolean value to the constructor: `true` if the initial state is signaled and `false` otherwise.
`AutoResetEvent` can also be used with the `static` <xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods.
Beginning with the .NET Framework version 2.0, <xref:System.Threading.AutoResetEvent> derives from the new <xref:System.Threading.EventWaitHandle> class. An <xref:System.Threading.AutoResetEvent> is functionally equivalent to an <xref:System.Threading.EventWaitHandle> created with <xref:System.Threading.EventResetMode.AutoReset?displayProperty=nameWithType>.
> There's no guarantee that every call to the <xref:System.Threading.EventWaitHandle.Set%2A> method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released. It's as if the second call did not happen. Also, if <xref:System.Threading.EventWaitHandle.Set%2A> is called when there are no threads waiting and the <xref:System.Threading.AutoResetEvent> is already signaled, the call has no effect.

You can control the initial state of an `AutoResetEvent` by passing a Boolean value to the constructor: `true` if the initial state is signaled and `false` otherwise.

`AutoResetEvent` can also be used with the `static` <xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods.

<xref:System.Threading.AutoResetEvent> derives from the <xref:System.Threading.EventWaitHandle> class. An <xref:System.Threading.AutoResetEvent> is functionally equivalent to an <xref:System.Threading.EventWaitHandle> created with <xref:System.Threading.EventResetMode.AutoReset?displayProperty=nameWithType>.

> [!NOTE]
> Unlike the <xref:System.Threading.AutoResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events.



## Examples
The following example shows how to use <xref:System.Threading.AutoResetEvent> to release one thread at a time, by calling the <xref:System.Threading.EventWaitHandle.Set%2A> method (on the base class) each time the user presses the **Enter** key. The example starts three threads, which wait on an <xref:System.Threading.AutoResetEvent> that was created in the signaled state. The first thread is released immediately, because the <xref:System.Threading.AutoResetEvent> is already in the signaled state. This resets the <xref:System.Threading.AutoResetEvent> to the non-signaled state, so that subsequent threads block. The blocked threads are not released until the user releases them one at a time by pressing the **Enter** key.

After the threads are released from the first <xref:System.Threading.AutoResetEvent>, they wait on another <xref:System.Threading.AutoResetEvent> that was created in the non-signaled state. All three threads block, so the <xref:System.Threading.EventWaitHandle.Set%2A> method must be called three times to release them all.

:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/simplerisbetter.cpp" id="Snippet3":::
:::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/simplerisbetter.cs" id="Snippet3":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/simplerisbetter.vb" id="Snippet3":::

> Unlike the <xref:System.Threading.AutoResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events.

> [!IMPORTANT]
> This type implements the <xref:System.IDisposable> interface. When you have finished using the type, you should dispose of it either directly or indirectly. To dispose of the type directly, call its <xref:System.IDisposable.Dispose%2A> method in a `try`/`catch` block. To dispose of it indirectly, use a language construct such as `using` (in C#) or `Using` (in Visual Basic). For more information, see the "Using an Object that Implements IDisposable" section on the <xref:System.IDisposable> interface page.

## Examples

The following example shows how to use <xref:System.Threading.AutoResetEvent> to release one thread at a time, by calling the <xref:System.Threading.EventWaitHandle.Set%2A> method (on the base class) each time the user presses the **Enter** key. The example starts three threads, which wait on an <xref:System.Threading.AutoResetEvent> that was created in the signaled state. The first thread is released immediately, because the <xref:System.Threading.AutoResetEvent> is already in the signaled state. This resets the <xref:System.Threading.AutoResetEvent> to the non-signaled state, so that subsequent threads block. The blocked threads are not released until the user releases them one at a time by pressing the **Enter** key.

After the threads are released from the first <xref:System.Threading.AutoResetEvent>, they wait on another <xref:System.Threading.AutoResetEvent> that was created in the non-signaled state. All three threads block, so the <xref:System.Threading.EventWaitHandle.Set%2A> method must be called three times to release them all.

:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/simplerisbetter.cpp" id="Snippet3":::
:::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/simplerisbetter.cs" id="Snippet3":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/simplerisbetter.vb" id="Snippet3":::

]]></format>
</remarks>
<threadsafe>This class is thread safe.</threadsafe>
Expand Down Expand Up @@ -149,21 +147,21 @@
<see langword="true" /> to set the initial state to signaled; <see langword="false" /> to set the initial state to non-signaled.</param>
<summary>Initializes a new instance of the <see cref="T:System.Threading.AutoResetEvent" /> class with a Boolean value indicating whether to set the initial state to signaled.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Examples
The following example uses an <xref:System.Threading.AutoResetEvent> to synchronize the activities of two threads. The first thread, which is the application thread, executes `Main`. It writes values to the protected resource, which is a `static` (`Shared` in Visual Basic) field named `number`. The second thread executes the static `ThreadProc` method, which reads the values written by `Main`.
The `ThreadProc` method waits for the <xref:System.Threading.AutoResetEvent>. When `Main` calls the <xref:System.Threading.EventWaitHandle.Set%2A> method on the <xref:System.Threading.AutoResetEvent>, the `ThreadProc` method reads one value. The <xref:System.Threading.AutoResetEvent> immediately resets, so the `ThreadProc` method waits again.
The program logic guarantees that the `ThreadProc` method will never read the same value two times. It does not guarantee that the `ThreadProc` method will read every value written by `Main`. That guarantee would require a second <xref:System.Threading.AutoResetEvent> lock.
After each write operation, `Main` yields by calling the <xref:System.Threading.Thread.Sleep%2A?displayProperty=nameWithType> method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations.
<format type="text/markdown"><![CDATA[

## Examples
The following example uses an <xref:System.Threading.AutoResetEvent> to synchronize the activities of two threads. The first thread, which is the application thread, executes `Main`. It writes values to the protected resource, which is a `static` (`Shared` in Visual Basic) field named `number`. The second thread executes the static `ThreadProc` method, which reads the values written by `Main`.

The `ThreadProc` method waits for the <xref:System.Threading.AutoResetEvent>. When `Main` calls the <xref:System.Threading.EventWaitHandle.Set%2A> method on the <xref:System.Threading.AutoResetEvent>, the `ThreadProc` method reads one value. The <xref:System.Threading.AutoResetEvent> immediately resets, so the `ThreadProc` method waits again.

The program logic guarantees that the `ThreadProc` method will never read the same value two times. It does not guarantee that the `ThreadProc` method will read every value written by `Main`. That guarantee would require a second <xref:System.Threading.AutoResetEvent> lock.

After each write operation, `Main` yields by calling the <xref:System.Threading.Thread.Sleep%2A?displayProperty=nameWithType> method, to give the second thread a chance to execute. Otherwise, on a single-processor computer `Main` would write many values between any two read operations.

:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/class1.cpp" id="Snippet1":::
:::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/class1.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/class1.vb" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/class1.vb" id="Snippet1":::

]]></format>
</remarks>
<altmember cref="T:System.Threading.WaitHandle" />
Expand Down Expand Up @@ -229,11 +227,12 @@
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The Set method releases a single thread. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it, or until its Reset method is called.
## Remarks

This method releases a single thread and then resets the event automatically. If there are no waiting threads, the wait handle remains signaled until a thread attempts to wait on it or until the `Reset` method is called.

> [!IMPORTANT]
> There is no guarantee that every call to the Set method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released - as if the second call did not happen. Also, if the Set method is called when there are no threads waiting and the <xref:System.Threading.AutoResetEvent> is already signaled, the call has no effect.
> There is no guarantee that every call to the `Set` method will release a thread. If two calls are too close together, so that the second call occurs before a thread has been released, only one thread is released - as if the second call did not happen. Also, if the `Set` method is called when there are no threads waiting and the <xref:System.Threading.AutoResetEvent> is already signaled, the call has no effect.

]]></format>
</remarks>
Expand Down
Loading