-
Notifications
You must be signed in to change notification settings - Fork 1.6k
/
Copy pathAutoResetEvent.xml
245 lines (220 loc) · 20.3 KB
/
AutoResetEvent.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
<Type Name="AutoResetEvent" FullName="System.Threading.AutoResetEvent">
<TypeSignature Language="C#" Value="public sealed class AutoResetEvent : System.Threading.EventWaitHandle" FrameworkAlternate="dotnet-uwp-10.0;net-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit AutoResetEvent extends System.Threading.EventWaitHandle" FrameworkAlternate="dotnet-uwp-10.0;net-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Threading.AutoResetEvent" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class AutoResetEvent
Inherits EventWaitHandle" FrameworkAlternate="dotnet-uwp-10.0;net-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="F#" Value="type AutoResetEvent = class
 inherit EventWaitHandle" FrameworkAlternate="dotnet-uwp-10.0;net-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="C++ CLI" Value="public ref class AutoResetEvent sealed : System::Threading::EventWaitHandle" FrameworkAlternate="dotnet-uwp-10.0;net-10.0;net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1" />
<TypeSignature Language="C#" Value="public sealed class AutoResetEvent : System.Threading.WaitHandle" FrameworkAlternate="netframework-1.1" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit AutoResetEvent extends System.Threading.WaitHandle" FrameworkAlternate="netframework-1.1" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class AutoResetEvent
Inherits WaitHandle" FrameworkAlternate="netframework-1.1" />
<TypeSignature Language="F#" Value="type AutoResetEvent = class
 inherit WaitHandle" FrameworkAlternate="netframework-1.1" />
<TypeSignature Language="C++ CLI" Value="public ref class AutoResetEvent sealed : System::Threading::WaitHandle" FrameworkAlternate="netframework-1.1" />
<AssemblyInfo>
<AssemblyName>System.Threading</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.1.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
<AssemblyVersion>10.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<TypeForwardingChain>
<TypeForwarding From="mscorlib" FromVersion="4.0.0.0" To="System.Threading" ToVersion="0.0.0.0" FrameworkAlternate="dotnet-uwp-10.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="10.0.0.0" FrameworkAlternate="net-10.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
</TypeForwardingChain>
<Base>
<BaseTypeName>System.Threading.EventWaitHandle</BaseTypeName>
<BaseTypeName FrameworkAlternate="netframework-1.1">System.Threading.WaitHandle</BaseTypeName>
</Base>
<Interfaces />
<Attributes>
<Attribute FrameworkAlternate="netframework-2.0;netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netframework-4.8.1">
<AttributeName Language="C#">[System.Runtime.InteropServices.ComVisible(true)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.InteropServices.ComVisible(true)>]</AttributeName>
</Attribute>
</Attributes>
<Docs>
<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"><.
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'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.
> [!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>
<altmember cref="T:System.Threading.WaitHandle" />
<related type="Article" href="/dotnet/standard/threading/">Managed Threading</related>
<related type="Article" href="/dotnet/standard/threading/overview-of-synchronization-primitives">Overview of synchronization primitives</related>
</Docs>
<Members>
<Member MemberName=".ctor">
<MemberSignature Language="C#" Value="public AutoResetEvent (bool initialState);" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig specialname rtspecialname instance void .ctor(bool initialState) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Threading.AutoResetEvent.#ctor(System.Boolean)" />
<MemberSignature Language="VB.NET" Value="Public Sub New (initialState As Boolean)" />
<MemberSignature Language="F#" Value="new System.Threading.AutoResetEvent : bool -> System.Threading.AutoResetEvent" Usage="new System.Threading.AutoResetEvent initialState" />
<MemberSignature Language="C++ CLI" Value="public:
 AutoResetEvent(bool initialState);" />
<MemberType>Constructor</MemberType>
<AssemblyInfo>
<AssemblyName>System.Threading</AssemblyName>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
<AssemblyVersion>4.0.10.0</AssemblyVersion>
<AssemblyVersion>4.1.0.0</AssemblyVersion>
<AssemblyVersion>4.1.1.0</AssemblyVersion>
<AssemblyVersion>4.1.2.0</AssemblyVersion>
<AssemblyVersion>5.0.0.0</AssemblyVersion>
<AssemblyVersion>6.0.0.0</AssemblyVersion>
<AssemblyVersion>7.0.0.0</AssemblyVersion>
<AssemblyVersion>8.0.0.0</AssemblyVersion>
<AssemblyVersion>9.0.0.0</AssemblyVersion>
<AssemblyVersion>10.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.0.5.0</AssemblyVersion>
<AssemblyVersion>4.0.0.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
<AssemblyVersion>2.0.0.0</AssemblyVersion>
<AssemblyVersion>2.1.0.0</AssemblyVersion>
</AssemblyInfo>
<Attributes>
<Attribute FrameworkAlternate="netframework-4.0">
<AttributeName Language="C#">[System.Security.SecuritySafeCritical]</AttributeName>
<AttributeName Language="F#">[<System.Security.SecuritySafeCritical>]</AttributeName>
</Attribute>
</Attributes>
<Parameters>
<Parameter Name="initialState" Type="System.Boolean" />
</Parameters>
<Docs>
<param name="initialState">
<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.
:::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":::
]]></format>
</remarks>
<altmember cref="T:System.Threading.WaitHandle" />
<related type="Article" href="/dotnet/standard/threading/">Managed Threading</related>
<related type="Article" href="/dotnet/standard/threading/overview-of-synchronization-primitives">Overview of synchronization primitives</related>
</Docs>
</Member>
<Member MemberName="Reset">
<MemberSignature Language="C#" Value="public bool Reset ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance bool Reset() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Threading.AutoResetEvent.Reset" />
<MemberSignature Language="VB.NET" Value="Public Function Reset () As Boolean" />
<MemberSignature Language="F#" Value="member this.Reset : unit -> bool" Usage="autoResetEvent.Reset " />
<MemberSignature Language="C++ CLI" Value="public:
 bool Reset();" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>System.Threading</AssemblyName>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Sets the state of the event to nonsignaled, which causes threads to block.</summary>
<returns>
<see langword="true" /> if the operation succeeds; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Set">
<MemberSignature Language="C#" Value="public bool Set ();" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance bool Set() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Threading.AutoResetEvent.Set" />
<MemberSignature Language="VB.NET" Value="Public Function Set () As Boolean" />
<MemberSignature Language="F#" Value="member this.Set : unit -> bool" Usage="autoResetEvent.Set " />
<MemberSignature Language="C++ CLI" Value="public:
 bool Set();" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>System.Threading</AssemblyName>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Sets the state of the event to signaled, which allows at most one waiting thread to proceed.</summary>
<returns>
<see langword="true" /> if the operation succeeds; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## 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.
]]></format>
</remarks>
</Docs>
</Member>
</Members>
</Type>