-
Notifications
You must be signed in to change notification settings - Fork 1.5k
/
RegisteredWaitHandle.xml
199 lines (182 loc) · 18.5 KB
/
RegisteredWaitHandle.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
<Type Name="RegisteredWaitHandle" FullName="System.Threading.RegisteredWaitHandle">
<TypeSignature Language="C#" Value="public sealed class RegisteredWaitHandle : MarshalByRefObject" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.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-2.0;netstandard-2.1" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit RegisteredWaitHandle extends System.MarshalByRefObject" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.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-2.0;netstandard-2.1" />
<TypeSignature Language="DocId" Value="T:System.Threading.RegisteredWaitHandle" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class RegisteredWaitHandle
Inherits MarshalByRefObject" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.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-2.0;netstandard-2.1" />
<TypeSignature Language="F#" Value="type RegisteredWaitHandle = class
 inherit MarshalByRefObject" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.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-2.0;netstandard-2.1" />
<TypeSignature Language="C++ CLI" Value="public ref class RegisteredWaitHandle sealed : MarshalByRefObject" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netcore-3.1;netframework-1.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-2.0;netstandard-2.1" />
<TypeSignature Language="C#" Value="public sealed class RegisteredWaitHandle" FrameworkAlternate="netcore-1.0;netcore-1.1" />
<TypeSignature Language="ILAsm" Value=".class public auto ansi sealed beforefieldinit RegisteredWaitHandle extends System.Object" FrameworkAlternate="netcore-1.0;netcore-1.1" />
<TypeSignature Language="VB.NET" Value="Public NotInheritable Class RegisteredWaitHandle" FrameworkAlternate="netcore-1.0;netcore-1.1" />
<TypeSignature Language="F#" Value="type RegisteredWaitHandle = class" FrameworkAlternate="netcore-1.0;netcore-1.1" />
<TypeSignature Language="C++ CLI" Value="public ref class RegisteredWaitHandle sealed" FrameworkAlternate="netcore-1.0;netcore-1.1" />
<AssemblyInfo>
<AssemblyName>System.Threading.ThreadPool</AssemblyName>
<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>
</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="netstandard" FromVersion="2.1.0.0" To="System.Threading.ThreadPool" ToVersion="5.0.0.0" FrameworkAlternate="net-5.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading.ThreadPool" ToVersion="6.0.0.0" FrameworkAlternate="net-6.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading.ThreadPool" ToVersion="7.0.0.0" FrameworkAlternate="net-7.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading.ThreadPool" ToVersion="8.0.0.0" FrameworkAlternate="net-8.0" />
<TypeForwarding From="netstandard" FromVersion="2.1.0.0" To="System.Threading.ThreadPool" ToVersion="9.0.0.0" FrameworkAlternate="net-9.0" />
</TypeForwardingChain>
<Base>
<BaseTypeName>System.MarshalByRefObject</BaseTypeName>
<BaseTypeName FrameworkAlternate="netcore-1.0;netcore-1.1">System.Object</BaseTypeName>
</Base>
<Interfaces />
<Attributes>
<Attribute FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]</AttributeName>
</Attribute>
<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 handle that has been registered when calling <see cref="M:System.Threading.ThreadPool.RegisterWaitForSingleObject(System.Threading.WaitHandle,System.Threading.WaitOrTimerCallback,System.Object,System.UInt32,System.Boolean)" />. This class cannot be inherited.</summary>
<remarks>
<format type="text/markdown"><![CDATA[
## Examples
The following example shows how to use a <xref:System.Threading.RegisteredWaitHandle> to determine why a callback method is called, and how to unregister a task if the callback occurred because the wait handle was signaled.
The example also shows how to use the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an <xref:System.Threading.AutoResetEvent>.
The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The <xref:System.Threading.RegisteredWaitHandle> that is returned by the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the <xref:System.Threading.RegisteredWaitHandle>.
In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method specifies the <xref:System.Threading.AutoResetEvent> that the task will wait for, a <xref:System.Threading.WaitOrTimerCallback> delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks.
When the main thread signals the <xref:System.Threading.AutoResetEvent> by calling its <xref:System.Threading.EventWaitHandle.Set%2A> method, the <xref:System.Threading.WaitOrTimerCallback> delegate is invoked. The `WaitProc` method tests <xref:System.Threading.RegisteredWaitHandle> to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the <xref:System.Threading.RegisteredWaitHandle>, stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console.
:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/CPP/source.cpp" id="Snippet1":::
:::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/VB/source.vb" id="Snippet1":::
]]></format>
</remarks>
<threadsafe>This type is thread safe.</threadsafe>
<related type="Article" href="/dotnet/standard/threading/the-managed-thread-pool">The managed thread pool</related>
</Docs>
<Members>
<Member MemberName="Finalize">
<MemberSignature Language="C#" Value="~RegisteredWaitHandle ();" />
<MemberSignature Language="ILAsm" Value=".method familyhidebysig virtual instance void Finalize() cil managed" />
<MemberSignature Language="DocId" Value="M:System.Threading.RegisteredWaitHandle.Finalize" />
<MemberSignature Language="VB.NET" Value="Finalize ()" />
<MemberSignature Language="F#" Value="override this.Finalize : unit -> unit" Usage="registeredWaitHandle.Finalize " />
<MemberSignature Language="C++ CLI" Value="!RegisteredWaitHandle ()" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>mscorlib</AssemblyName>
<AssemblyVersion>1.0.5000.0</AssemblyVersion>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>System.Threading.ThreadPool</AssemblyName>
</AssemblyInfo>
<AssemblyInfo>
<AssemblyName>netstandard</AssemblyName>
</AssemblyInfo>
<ReturnValue>
<ReturnType>System.Void</ReturnType>
</ReturnValue>
<Parameters />
<Docs>
<summary>Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
<Member MemberName="Unregister">
<MemberSignature Language="C#" Value="public bool Unregister (System.Threading.WaitHandle? waitObject);" FrameworkAlternate="net-5.0;net-6.0;net-7.0;net-8.0;net-9.0;netcore-3.0;netcore-3.1" />
<MemberSignature Language="ILAsm" Value=".method public hidebysig instance bool Unregister(class System.Threading.WaitHandle waitObject) cil managed" />
<MemberSignature Language="DocId" Value="M:System.Threading.RegisteredWaitHandle.Unregister(System.Threading.WaitHandle)" />
<MemberSignature Language="VB.NET" Value="Public Function Unregister (waitObject As WaitHandle) As Boolean" />
<MemberSignature Language="F#" Value="member this.Unregister : System.Threading.WaitHandle -> bool" Usage="registeredWaitHandle.Unregister waitObject" />
<MemberSignature Language="C++ CLI" Value="public:
 bool Unregister(System::Threading::WaitHandle ^ waitObject);" />
<MemberSignature Language="C#" Value="public bool Unregister (System.Threading.WaitHandle waitObject);" FrameworkAlternate="netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netframework-1.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-2.0;netstandard-2.1" />
<MemberType>Method</MemberType>
<AssemblyInfo>
<AssemblyName>System.Threading.ThreadPool</AssemblyName>
<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>
</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="net-8.0;net-9.0">
<AttributeName Language="C#">[System.Runtime.CompilerServices.NullableContext(2)]</AttributeName>
<AttributeName Language="F#">[<System.Runtime.CompilerServices.NullableContext(2)>]</AttributeName>
</Attribute>
<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>
<Attribute FrameworkAlternate="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.Security.SecuritySafeCritical]</AttributeName>
<AttributeName Language="F#">[<System.Security.SecuritySafeCritical>]</AttributeName>
</Attribute>
</Attributes>
<ReturnValue>
<ReturnType>System.Boolean</ReturnType>
</ReturnValue>
<Parameters>
<Parameter Name="waitObject" Type="System.Threading.WaitHandle" />
</Parameters>
<Docs>
<param name="waitObject">The <see cref="T:System.Threading.WaitHandle" /> to be signaled.</param>
<summary>Cancels a registered wait operation issued by the <see cref="M:System.Threading.ThreadPool.RegisterWaitForSingleObject(System.Threading.WaitHandle,System.Threading.WaitOrTimerCallback,System.Object,System.UInt32,System.Boolean)" /> method.</summary>
<returns>
<see langword="true" /> if the function succeeds; otherwise, <see langword="false" />.</returns>
<remarks>
<format type="text/markdown"><![CDATA[
## Remarks
If `waitObject` is specified, it is signaled only if the <xref:System.Threading.RegisteredWaitHandle> is successfully unregistered. If a callback method is in progress when <xref:System.Threading.RegisteredWaitHandle.Unregister%2A> executes, `waitObject` is not signaled until the callback method completes. In particular, if a callback method executes <xref:System.Threading.RegisteredWaitHandle.Unregister%2A>, `waitObject` is not signaled until that callback method completes.
## Examples
The following example shows how to use the <xref:System.Threading.RegisteredWaitHandle.Unregister%2A> method to unregister a task if a callback occurred because the wait handle was signaled.
The example also shows how to use the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method to execute a specified callback method when a specified wait handle is signaled. In this example, the callback method is `WaitProc`, and the wait handle is an <xref:System.Threading.AutoResetEvent>.
The example defines a `TaskInfo` class to hold the information that is passed to the callback when it executes. The example creates a `TaskInfo` object and assigns it some string data. The <xref:System.Threading.RegisteredWaitHandle> that is returned by the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method is assigned to the `Handle` field of the `TaskInfo` object so that the callback method has access to the <xref:System.Threading.RegisteredWaitHandle>.
In addition to specifying `TaskInfo` as the object to pass to the callback method, the call to the <xref:System.Threading.ThreadPool.RegisterWaitForSingleObject%2A> method specifies the <xref:System.Threading.AutoResetEvent> that the task will wait for, a <xref:System.Threading.WaitOrTimerCallback> delegate that represents the `WaitProc` callback method, a one second time-out interval, and multiple callbacks.
When the main thread signals the <xref:System.Threading.AutoResetEvent> by calling its <xref:System.Threading.EventWaitHandle.Set%2A> method, the <xref:System.Threading.WaitOrTimerCallback> delegate is invoked. The `WaitProc` method tests <xref:System.Threading.RegisteredWaitHandle> to determine whether a time-out occurred. If the callback was invoked because the wait handle was signaled, the `WaitProc` method unregisters the <xref:System.Threading.RegisteredWaitHandle>, stopping additional callbacks. In the case of a time-out, the task continues to wait. The `WaitProc` method ends by printing a message to the console.
:::code language="cpp" source="~/snippets/cpp/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/CPP/source.cpp" id="Snippet1":::
:::code language="csharp" source="~/snippets/csharp/System.Threading/RegisteredWaitHandle/Overview/source.cs" id="Snippet1":::
:::code language="vb" source="~/snippets/visualbasic/VS_Snippets_CLR_System/system.Threading.ThreadPool RegisterWaitForSingleObject0/VB/source.vb" id="Snippet1":::
]]></format>
</remarks>
<related type="Article" href="/dotnet/standard/threading/the-managed-thread-pool">The managed thread pool</related>
</Docs>
</Member>
</Members>
</Type>