|
55 | 55 | </Attribute> |
56 | 56 | </Attributes> |
57 | 57 | <Docs> |
58 | | - <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> |
| 58 | + <summary>Represents a thread synchronization event that, when signaled, releases one single waiting thread and then resets automatically. This class cannot be inherited.</summary> |
59 | 59 | <remarks> |
60 | | - <format type="text/markdown">< section of the [Overview of synchronization primitives](/dotnet/standard/threading/overview-of-synchronization-primitives) article. |
64 | | - |
65 | | -> [!IMPORTANT] |
66 | | -> 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. |
67 | | - |
68 | | - 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. |
69 | | - |
70 | | - 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. |
71 | | - |
72 | | - 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. |
73 | | - |
| 60 | + <format type="text/markdown"><. |
| 65 | +
|
| 66 | +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. |
| 67 | +
|
| 68 | +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. |
| 69 | +
|
74 | 70 | > [!IMPORTANT] |
75 | | -> 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. |
76 | | - |
77 | | - 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. |
78 | | - |
79 | | - `AutoResetEvent` can also be used with the `static` <xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods. |
80 | | - |
81 | | - 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>. |
82 | | - |
| 71 | +> 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. |
| 72 | +
|
| 73 | +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. |
| 74 | +
|
| 75 | +`AutoResetEvent` can also be used with the `static` <xref:System.Threading.WaitHandle.WaitAll%2A> and <xref:System.Threading.WaitHandle.WaitAny%2A> methods. |
| 76 | +
|
| 77 | +<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>. |
| 78 | +
|
83 | 79 | > [!NOTE] |
84 | | -> Unlike the <xref:System.Threading.AutoResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events. |
85 | | - |
86 | | - |
87 | | - |
88 | | -## Examples |
89 | | - 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. |
90 | | - |
91 | | - 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. |
92 | | - |
93 | | - :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/simplerisbetter.cpp" id="Snippet3"::: |
94 | | - :::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/simplerisbetter.cs" id="Snippet3"::: |
95 | | - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/simplerisbetter.vb" id="Snippet3"::: |
96 | | - |
| 80 | +> Unlike the <xref:System.Threading.AutoResetEvent> class, the <xref:System.Threading.EventWaitHandle> class provides access to named system synchronization events. |
| 81 | +
|
| 82 | +> [!IMPORTANT] |
| 83 | +> 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. |
| 84 | +
|
| 85 | +## Examples |
| 86 | +
|
| 87 | +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. |
| 88 | +
|
| 89 | +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. |
| 90 | +
|
| 91 | +:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/simplerisbetter.cpp" id="Snippet3"::: |
| 92 | +:::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/simplerisbetter.cs" id="Snippet3"::: |
| 93 | +:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/simplerisbetter.vb" id="Snippet3"::: |
| 94 | +
|
97 | 95 | ]]></format> |
98 | 96 | </remarks> |
99 | 97 | <threadsafe>This class is thread safe.</threadsafe> |
|
149 | 147 | <see langword="true" /> to set the initial state to signaled; <see langword="false" /> to set the initial state to non-signaled.</param> |
150 | 148 | <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> |
151 | 149 | <remarks> |
152 | | - <format type="text/markdown"><![CDATA[ |
153 | | - |
154 | | -## Examples |
155 | | - 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`. |
156 | | - |
157 | | - 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. |
158 | | - |
159 | | - 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. |
160 | | - |
161 | | - 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. |
162 | | - |
| 150 | + <format type="text/markdown"><![CDATA[ |
| 151 | +
|
| 152 | +## Examples |
| 153 | + 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`. |
| 154 | +
|
| 155 | + 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. |
| 156 | +
|
| 157 | + 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. |
| 158 | +
|
| 159 | + 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. |
| 160 | +
|
163 | 161 | :::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/CPP/class1.cpp" id="Snippet1"::: |
164 | 162 | :::code language="csharp" source="~/snippets/csharp/System.Threading/AutoResetEvent/Overview/class1.cs" id="Snippet1"::: |
165 | | - :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/class1.vb" id="Snippet1"::: |
166 | | - |
| 163 | + :::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.AutoResetEvent/VB/class1.vb" id="Snippet1"::: |
| 164 | +
|
167 | 165 | ]]></format> |
168 | 166 | </remarks> |
169 | 167 | <altmember cref="T:System.Threading.WaitHandle" /> |
|
229 | 227 | <remarks> |
230 | 228 | <format type="text/markdown"><![CDATA[ |
231 | 229 |
|
232 | | -## Remarks |
233 | | -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. |
| 230 | +## Remarks |
| 231 | +
|
| 232 | +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. |
234 | 233 |
|
235 | 234 | > [!IMPORTANT] |
236 | | -> 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. |
| 235 | +> 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. |
237 | 236 |
|
238 | 237 | ]]></format> |
239 | 238 | </remarks> |
|
0 commit comments