Skip to content

Commit 4383bc8

Browse files
sharwellsharwell
committed
Initial documentation page for asynchronous services
1 parent 6186bb2 commit 4383bc8

4 files changed

Lines changed: 116 additions & 0 deletions

File tree

‎src/Documentation/Content/AsynchronousServices.aml‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<topic id="32cc6156-3b31-4450-b209-b55fcfc0a210" revisionNumber="1">
3+
<developerConceptualDocument
4+
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
5+
xmlns:xlink="http://www.w3.org/1999/xlink">
6+
7+
<introduction>
8+
<para>
9+
The openstack.net SDK is migrating to an asynchronous service model for ongoing feature support.
10+
This page contains information about several aspects of the asynchronous interfaces which could
11+
result in some confusion during development. It also describes the inclusion of extension methods
12+
that allow new product features to be used in code that is not allowed to make asynchronous API
13+
calls.
14+
</para>
15+
</introduction>
16+
17+
<section address="Exceptions">
18+
<title>Exceptions Thrown by Asynchronous Methods</title>
19+
<content>
20+
<para>
21+
Asynchronous methods are capable of throwing exceptions before creating a
22+
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> or during the asynchronous
23+
execution of the task itself. The asynchronous service interfaces do not distinguish between these
24+
two cases, allowing for any of the specified exceptions to be thrown in either manner.
25+
</para>
26+
<list class="bullet">
27+
<listItem>
28+
<para>
29+
Exceptions thrown prior to the creation of the
30+
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> object representing the
31+
asynchronous operation must be caught directly by the calling code. For example, if the code
32+
throws an <codeEntityReference>T:System.ArgumentNullException</codeEntityReference> in this
33+
manner, the calling code would need to contain a
34+
<codeInline>catch(ArgumentNullException)</codeInline> or
35+
<codeInline>catch(ArgumentException)</codeInline> handler to handle the exception.
36+
</para>
37+
</listItem>
38+
<listItem>
39+
<para>
40+
Exceptions thrown during the asynchronous exceution of the task are wrapped in an
41+
<codeEntityReference>T:System.AggregateException</codeEntityReference> object and returned by the
42+
<codeEntityReference>P:System.Threading.Tasks.Task.Exception</codeEntityReference> property.
43+
Exceptions thrown in this manner must be handled either by a task continuation that checks the
44+
<codeEntityReference>P:System.Threading.Tasks.Task.Exception</codeEntityReference> property, or
45+
by calling <codeEntityReference autoUpgrade="true">M:System.Threading.Tasks.Task.Wait</codeEntityReference>
46+
or checking the <codeEntityReference>P:System.Threading.Tasks.Task`1.Result</codeEntityReference>
47+
property within an exception handling block that includes a
48+
<codeInline>catch(AggregateException)</codeInline> handler.
49+
</para>
50+
</listItem>
51+
</list>
52+
</content>
53+
</section>
54+
55+
<section address="SynchronousExtensions">
56+
<title>Synchronous Extensions</title>
57+
<content>
58+
<para>
59+
The namespace <codeEntityReference>N:net.openstack.Core.Synchronous</codeEntityReference> contains extension
60+
methods that allow methods in an asynchronous service interface to be invoked synchronously. These extension
61+
methods are not recommended for use in new development, but are provided as a compatibility aid for projects
62+
where external restrictions preclude the direct use of the asynchronous APIs. These extension methods perform
63+
the following functions:
64+
</para>
65+
<list class="bullet">
66+
<listItem>
67+
<para>
68+
Invoke the asynchronous method, wait for the resulting
69+
<codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> to complete, and (where
70+
applicable) return the task result.
71+
</para>
72+
</listItem>
73+
<listItem>
74+
<para>
75+
If an exception is thrown during the asynchronous execution of the method and wrapped in an
76+
<codeEntityReference>T:System.AggregateException</codeEntityReference>, the extension method unwraps the inner exception and throws
77+
it directly, just as would occur if the underlying method were executed synchronously.
78+
</para>
79+
</listItem>
80+
</list>
81+
<para>
82+
The extensions for synchronous API calls do not expose all features of the underlying asynchronous API. In
83+
particular, the following limitations apply.
84+
</para>
85+
<list class="bullet">
86+
<listItem>
87+
<para>
88+
For asynchronous methods taking an <codeEntityReference>T:net.openstack.Core.AsyncCompletionOption</codeEntityReference> parameter to control
89+
the behavior of the task created for asynchronous server-side operations, the synchronous extension
90+
always passes <codeEntityReference>F:net.openstack.Core.AsyncCompletionOption.RequestSubmitted</codeEntityReference> for the argument.
91+
</para>
92+
</listItem>
93+
<listItem>
94+
<para>
95+
The synchronous extensions always pass <codeEntityReference>P:System.Threading.CancellationToken.None</codeEntityReference> for the
96+
<codeEntityReference>T:System.Threading.CancellationToken</codeEntityReference> argument, and do not support asynchronous cancellation of
97+
the call.
98+
</para>
99+
</listItem>
100+
<listItem>
101+
<para>
102+
The synchronous extensions do not support progress callbacks, and pass <codeInline>null</codeInline>
103+
to APIs with an <codeEntityReference>T:net.openstack.Core.IProgress`1</codeEntityReference> parameter.
104+
</para>
105+
</listItem>
106+
</list>
107+
</content>
108+
</section>
109+
110+
<relatedTopics>
111+
</relatedTopics>
112+
</developerConceptualDocument>
113+
</topic>

‎src/Documentation/Documentation.v3.5.shfbproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@
101101
</ProjectReference>
102102
</ItemGroup>
103103
<ItemGroup>
104+
<None Include="Content\AsynchronousServices.aml" />
104105
<None Include="Content\License.aml" />
105106
<None Include="Content\MSHelpViewerRoot.aml" />
106107
<None Include="Content\PreliminaryFeatures.aml" />

‎src/Documentation/Documentation.v4.0.shfbproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,7 @@
101101
</ProjectReference>
102102
</ItemGroup>
103103
<ItemGroup>
104+
<None Include="Content\AsynchronousServices.aml" />
104105
<None Include="Content\License.aml" />
105106
<None Include="Content\MSHelpViewerRoot.aml" />
106107
<None Include="Content\PreliminaryFeatures.aml" />

‎src/Documentation/OpenStackSDK.content‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,5 @@
1616
</HelpKeywords>
1717
</Topic>
1818
<Topic id="9c4a6074-9d84-4488-9565-50ecb5049ffe" visible="True" title="Preliminary Features" />
19+
<Topic id="32cc6156-3b31-4450-b209-b55fcfc0a210" visible="True" title="Asynchronous Services" />
1920
</Topics>

0 commit comments

Comments
 (0)