Skip to content

Commit 1402947

Browse files
Tsung-Wei HuangTsung-Wei Huang
Tsung-Wei Huang
authored and
Tsung-Wei Huang
committed
updated documentation for dependent_async
1 parent 524eb52 commit 1402947

11 files changed

Lines changed: 349 additions & 114 deletions

‎docs/DependentAsyncTasking.html‎

Lines changed: 40 additions & 4 deletions
Large diffs are not rendered by default.

‎docs/DynamicTasking.html‎

Lines changed: 59 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -191,39 +191,39 @@ <h3>Contents</h3>
191191
<text text-anchor="middle" x="331" y="-511.05">Subflow: 5</text>
192192
</g>
193193
<g class="m-cluster">
194-
<title>cluster_p0x7fe918000c48</title>
195-
<polygon points="418,-88.77 418,-347.08 638,-347.08 638,-88.77 418,-88.77"/>
196-
<text text-anchor="middle" x="528" y="-330.28">Subflow: 3</text>
194+
<title>cluster_p0x7fe918000b90</title>
195+
<polygon points="252,-88.77 252,-493.85 638,-493.85 638,-88.77 252,-88.77"/>
196+
<text text-anchor="middle" x="445" y="-477.05">Subflow: 4</text>
197197
</g>
198198
<g class="m-cluster">
199-
<title>cluster_p0x7fe918000d00</title>
200-
<polygon points="488,-161.54 488,-313.08 630,-313.08 630,-161.54 488,-161.54"/>
201-
<text text-anchor="middle" x="559" y="-296.28">Subflow: 2</text>
199+
<title>cluster_p0x7fe910000b90</title>
200+
<polygon points="410,-161.54 410,-459.85 630,-459.85 630,-161.54 410,-161.54"/>
201+
<text text-anchor="middle" x="520" y="-443.05">Subflow: 3</text>
202202
</g>
203203
<g class="m-cluster">
204-
<title>cluster_p0x7fe918000b90</title>
205-
<polygon points="24,-88.77 24,-493.85 410,-493.85 410,-88.77 24,-88.77"/>
206-
<text text-anchor="middle" x="217" y="-477.05">Subflow: 4</text>
204+
<title>cluster_p0x7fe918000fe0</title>
205+
<polygon points="480,-234.31 480,-425.85 622,-425.85 622,-234.31 480,-234.31"/>
206+
<text text-anchor="middle" x="551" y="-409.05">Subflow: 2</text>
207207
</g>
208208
<g class="m-cluster">
209209
<title>cluster_p0x7fe910000c48</title>
210210
<polygon points="260,-161.54 260,-313.08 402,-313.08 402,-161.54 260,-161.54"/>
211211
<text text-anchor="middle" x="331" y="-296.28">Subflow: 2</text>
212212
</g>
213213
<g class="m-cluster">
214-
<title>cluster_p0x7fe910000b90</title>
215-
<polygon points="32,-161.54 32,-459.85 252,-459.85 252,-161.54 32,-161.54"/>
216-
<text text-anchor="middle" x="142" y="-443.05">Subflow: 3</text>
214+
<title>cluster_p0x7fe918000c48</title>
215+
<polygon points="24,-88.77 24,-347.08 244,-347.08 244,-88.77 24,-88.77"/>
216+
<text text-anchor="middle" x="134" y="-330.28">Subflow: 3</text>
217217
</g>
218218
<g class="m-cluster">
219-
<title>cluster_p0x7fe918000fe0</title>
220-
<polygon points="102,-234.31 102,-425.85 244,-425.85 244,-234.31 102,-234.31"/>
221-
<text text-anchor="middle" x="173" y="-409.05">Subflow: 2</text>
219+
<title>cluster_p0x7fe918000d00</title>
220+
<polygon points="94,-161.54 94,-313.08 236,-313.08 236,-161.54 94,-161.54"/>
221+
<text text-anchor="middle" x="165" y="-296.28">Subflow: 2</text>
222222
</g>
223223
<g class="m-node m-flat">
224224
<title>p0xa445c0</title>
225-
<ellipse cx="392" cy="-42.38" rx="27" ry="18.27"/>
226-
<text text-anchor="middle" x="392" y="-38.58">5</text>
225+
<ellipse cx="248" cy="-42.38" rx="27" ry="18.27"/>
226+
<text text-anchor="middle" x="248" y="-38.58">5</text>
227227
</g>
228228
<g class="m-node m-flat">
229229
<title>p0x7fe918000b90</title>
@@ -232,58 +232,58 @@ <h3>Contents</h3>
232232
</g>
233233
<g class="m-edge">
234234
<title>p0x7fe918000b90&#45;&gt;p0xa445c0</title>
235-
<path d="M344.24,-98.8C352.31,-89.43 362.79,-77.27 371.87,-66.73"/>
236-
<polygon points="374.91,-69.57 378.79,-59.71 369.61,-65 374.91,-69.57"/>
235+
<path d="M314.6,-100.17C302.55,-89.9 285.98,-75.77 272.38,-64.17"/>
236+
<polygon points="275.24,-61.16 265.36,-57.34 270.7,-66.49 275.24,-61.16"/>
237237
</g>
238238
<g class="m-node m-flat">
239239
<title>p0x7fe910000b90</title>
240-
<ellipse cx="174" cy="-187.92" rx="27" ry="18.27"/>
241-
<text text-anchor="middle" x="174" y="-184.12">3</text>
240+
<ellipse cx="445" cy="-187.92" rx="27" ry="18.27"/>
241+
<text text-anchor="middle" x="445" y="-184.12">3</text>
242242
</g>
243243
<g class="m-edge">
244244
<title>p0x7fe910000b90&#45;&gt;p0x7fe918000b90</title>
245-
<path d="M196.16,-176.93C223.04,-164.82 268.56,-144.3 299.18,-130.5"/>
246-
<polygon points="300.27,-133.39 307.95,-126.09 297.4,-127.01 300.27,-133.39"/>
245+
<path d="M426.04,-174.4C419.7,-170.26 412.57,-165.66 406,-161.54 390.92,-152.07 373.96,-141.78 359.98,-133.39"/>
246+
<polygon points="362.23,-130.06 351.85,-127.92 358.63,-136.06 362.23,-130.06"/>
247247
</g>
248248
<g class="m-node m-flat">
249249
<title>p0x7fe918000fe0</title>
250-
<ellipse cx="174" cy="-260.69" rx="27" ry="18.27"/>
251-
<text text-anchor="middle" x="174" y="-256.89">2</text>
250+
<ellipse cx="517" cy="-260.69" rx="27" ry="18.27"/>
251+
<text text-anchor="middle" x="517" y="-256.89">2</text>
252252
</g>
253253
<g class="m-edge">
254254
<title>p0x7fe918000fe0&#45;&gt;p0x7fe910000b90</title>
255-
<path d="M174,-242.2C174,-234.66 174,-225.65 174,-217.2"/>
256-
<polygon points="177.5,-217.22 174,-207.22 170.5,-217.22 177.5,-217.22"/>
255+
<path d="M502.08,-245.03C492.14,-235.26 478.88,-222.23 467.65,-211.18"/>
256+
<polygon points="470.48,-209.08 460.9,-204.57 465.58,-214.07 470.48,-209.08"/>
257257
</g>
258258
<g class="m-node m-flat">
259259
<title>p0x7fe918001150</title>
260-
<ellipse cx="209" cy="-373.46" rx="27" ry="18.27"/>
261-
<text text-anchor="middle" x="209" y="-369.66">1</text>
260+
<ellipse cx="587" cy="-373.46" rx="27" ry="18.27"/>
261+
<text text-anchor="middle" x="587" y="-369.66">1</text>
262262
</g>
263263
<g class="m-edge">
264264
<title>p0x7fe918001150&#45;&gt;p0x7fe918000fe0</title>
265-
<path d="M203.53,-355.16C197.96,-337.52 189.23,-309.89 182.7,-289.24"/>
266-
<polygon points="185.78,-288.36 179.43,-279.88 179.11,-290.47 185.78,-288.36"/>
265+
<path d="M576.67,-356.12C565.13,-337.85 546.3,-308.06 532.88,-286.83"/>
266+
<polygon points="535.44,-285.33 527.14,-278.74 529.53,-289.07 535.44,-285.33"/>
267267
</g>
268268
<g class="m-node m-flat">
269269
<title>p0x7fe918001208</title>
270-
<ellipse cx="137" cy="-373.46" rx="27" ry="18.27"/>
271-
<text text-anchor="middle" x="137" y="-369.66">0</text>
270+
<ellipse cx="515" cy="-373.46" rx="27" ry="18.27"/>
271+
<text text-anchor="middle" x="515" y="-369.66">0</text>
272272
</g>
273273
<g class="m-edge">
274274
<title>p0x7fe918001208&#45;&gt;p0x7fe918000fe0</title>
275-
<path d="M142.78,-355.16C148.67,-337.52 157.9,-309.89 164.8,-289.24"/>
276-
<polygon points="168.41,-290.47 168.26,-279.88 161.77,-288.26 168.41,-290.47"/>
275+
<path d="M515.31,-355.16C515.63,-337.78 516.11,-310.72 516.49,-290.17"/>
276+
<polygon points="520,-290.31 516.68,-280.25 513,-290.18 520,-290.31"/>
277277
</g>
278278
<g class="m-node m-flat">
279279
<title>p0x7fe918001098</title>
280-
<ellipse cx="67" cy="-260.69" rx="27" ry="18.27"/>
281-
<text text-anchor="middle" x="67" y="-256.89">1</text>
280+
<ellipse cx="445" cy="-260.69" rx="27" ry="18.27"/>
281+
<text text-anchor="middle" x="445" y="-256.89">1</text>
282282
</g>
283283
<g class="m-edge">
284284
<title>p0x7fe918001098&#45;&gt;p0x7fe910000b90</title>
285-
<path d="M83.06,-245.79C87.76,-241.93 92.99,-237.83 98,-234.31 112.71,-223.98 129.85,-213.61 144.13,-205.39"/>
286-
<polygon points="145.52,-208.06 152.49,-200.08 142.06,-201.97 145.52,-208.06"/>
285+
<path d="M445,-242.2C445,-234.66 445,-225.65 445,-217.2"/>
286+
<polygon points="448.5,-217.22 445,-207.22 441.5,-217.22 448.5,-217.22"/>
287287
</g>
288288
<g class="m-node m-flat">
289289
<title>p0x7fe910000c48</title>
@@ -317,53 +317,53 @@ <h3>Contents</h3>
317317
</g>
318318
<g class="m-node m-flat">
319319
<title>p0x7fe918000c48</title>
320-
<ellipse cx="453" cy="-115.15" rx="27" ry="18.27"/>
321-
<text text-anchor="middle" x="453" y="-111.35">3</text>
320+
<ellipse cx="166" cy="-115.15" rx="27" ry="18.27"/>
321+
<text text-anchor="middle" x="166" y="-111.35">3</text>
322322
</g>
323323
<g class="m-edge">
324324
<title>p0x7fe918000c48&#45;&gt;p0xa445c0</title>
325-
<path d="M439.76,-98.8C431.69,-89.43 421.21,-77.27 412.13,-66.73"/>
326-
<polygon points="414.39,-65 405.21,-59.71 409.09,-69.57 414.39,-65"/>
325+
<path d="M182.2,-100.17C193.99,-90 210.17,-76.03 223.53,-64.5"/>
326+
<polygon points="225.55,-66.52 230.83,-57.34 220.98,-61.22 225.55,-66.52"/>
327327
</g>
328328
<g class="m-node m-flat">
329329
<title>p0x7fe918000d00</title>
330-
<ellipse cx="525" cy="-187.92" rx="27" ry="18.27"/>
331-
<text text-anchor="middle" x="525" y="-184.12">2</text>
330+
<ellipse cx="166" cy="-187.92" rx="27" ry="18.27"/>
331+
<text text-anchor="middle" x="166" y="-184.12">2</text>
332332
</g>
333333
<g class="m-edge">
334334
<title>p0x7fe918000d00&#45;&gt;p0x7fe918000c48</title>
335-
<path d="M510.08,-172.26C500.14,-162.49 486.88,-149.46 475.65,-138.41"/>
336-
<polygon points="478.48,-136.31 468.9,-131.8 473.58,-141.31 478.48,-136.31"/>
335+
<path d="M166,-169.43C166,-161.89 166,-152.88 166,-144.43"/>
336+
<polygon points="169.5,-144.45 166,-134.45 162.5,-144.45 169.5,-144.45"/>
337337
</g>
338338
<g class="m-node m-flat">
339339
<title>p0x7fe918000e70</title>
340-
<ellipse cx="595" cy="-260.69" rx="27" ry="18.27"/>
341-
<text text-anchor="middle" x="595" y="-256.89">1</text>
340+
<ellipse cx="201" cy="-260.69" rx="27" ry="18.27"/>
341+
<text text-anchor="middle" x="201" y="-256.89">1</text>
342342
</g>
343343
<g class="m-edge">
344344
<title>p0x7fe918000e70&#45;&gt;p0x7fe918000d00</title>
345-
<path d="M580.5,-245.03C570.83,-235.26 557.94,-222.23 547.02,-211.18"/>
346-
<polygon points="550.01,-209.22 540.49,-204.57 545.03,-214.14 550.01,-209.22"/>
345+
<path d="M192.71,-242.92C188.61,-234.64 183.57,-224.45 178.98,-215.16"/>
346+
<polygon points="181.81,-213.99 174.23,-206.57 175.53,-217.09 181.81,-213.99"/>
347347
</g>
348348
<g class="m-node m-flat">
349349
<title>p0x7fe918000f28</title>
350-
<ellipse cx="523" cy="-260.69" rx="27" ry="18.27"/>
351-
<text text-anchor="middle" x="523" y="-256.89">0</text>
350+
<ellipse cx="129" cy="-260.69" rx="27" ry="18.27"/>
351+
<text text-anchor="middle" x="129" y="-256.89">0</text>
352352
</g>
353353
<g class="m-edge">
354354
<title>p0x7fe918000f28&#45;&gt;p0x7fe918000d00</title>
355-
<path d="M523.49,-242.2C523.71,-234.66 523.96,-225.65 524.2,-217.2"/>
356-
<polygon points="527.73,-217.31 524.51,-207.22 520.73,-217.11 527.73,-217.31"/>
355+
<path d="M137.77,-242.92C142.1,-234.64 147.43,-224.45 152.28,-215.16"/>
356+
<polygon points="155.76,-217.06 157.29,-206.57 149.56,-213.82 155.76,-217.06"/>
357357
</g>
358358
<g class="m-node m-flat">
359359
<title>p0x7fe918000db8</title>
360-
<ellipse cx="453" cy="-187.92" rx="27" ry="18.27"/>
361-
<text text-anchor="middle" x="453" y="-184.12">1</text>
360+
<ellipse cx="59" cy="-187.92" rx="27" ry="18.27"/>
361+
<text text-anchor="middle" x="59" y="-184.12">1</text>
362362
</g>
363363
<g class="m-edge">
364364
<title>p0x7fe918000db8&#45;&gt;p0x7fe918000c48</title>
365-
<path d="M453,-169.43C453,-161.89 453,-152.88 453,-144.43"/>
366-
<polygon points="456.5,-144.45 453,-134.45 449.5,-144.45 456.5,-144.45"/>
365+
<path d="M75.06,-173.02C79.76,-169.16 84.99,-165.06 90,-161.54 104.71,-151.21 121.85,-140.84 136.13,-132.63"/>
366+
<polygon points="137.52,-135.29 144.49,-127.31 134.06,-129.21 137.52,-135.29"/>
367367
</g>
368368
</g>
369369
</svg>

‎docs/classtf_1_1AsyncTask.html‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,12 @@ <h3>Contents</h3>
6161
</li>
6262
</ul>
6363
</nav>
64-
<p>An async-task is a lightweight handle that leverages <a href="http://en.cppreference.com/w/cpp/memory/shared_ptr.html" class="m-doc-external">std::<wbr />shared_ptr</a> to retain shared ownership of a dependent asynchronous task created by an executor (e.g., <a href="classtf_1_1Executor.html#aee02b63d3a91ad5ca5a1c0e71f3e128f" class="m-doc">tf::<wbr />Executor::<wbr />dependent_async</a>). The purpose of shared ownership is to avoid potential ABA problem when creating asynchronous tasks with dependents that already vanished.</p>
64+
<p>A <a href="classtf_1_1AsyncTask.html" class="m-doc">tf::<wbr />AsyncTask</a> is a lightweight handle that retains <em>shared</em> ownership of a dependent async task created by an executor. This shared ownership ensures that the async task remains alive when adding it to the dependency list of another async task, thus avoiding the classical <a href="https://en.wikipedia.org/wiki/ABA_problem">ABA problem</a>.</p><pre class="m-code"><span class="c1">// main thread retains shared ownership of async task A</span>
65+
<span class="n">tf</span><span class="o">::</span><span class="n">AsyncTask</span><span class="w"> </span><span class="n">A</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">executor</span><span class="p">.</span><span class="n">silent_dependent_async</span><span class="p">([](){});</span>
66+
67+
<span class="c1">// task A remains alive (i.e., at least one ref count by the main thread) </span>
68+
<span class="c1">// when being added to the dependency list of async task B</span>
69+
<span class="n">tf</span><span class="o">::</span><span class="n">AsyncTask</span><span class="w"> </span><span class="n">B</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">executor</span><span class="p">.</span><span class="n">silent_dependent_async</span><span class="p">([](){},</span><span class="w"> </span><span class="n">A</span><span class="p">);</span></pre><p>Currently, <a href="classtf_1_1AsyncTask.html" class="m-doc">tf::<wbr />AsyncTask</a> is implemented based on C++ smart pointer <a href="http://en.cppreference.com/w/cpp/memory/shared_ptr.html" class="m-doc-external">std::<wbr />shared_ptr</a> and is considered cheap to copy or move as long as only a handful of objects own it. When a worker completes an async task, it will remove the task from the executor, decrementing the number of shared owners by one. If that counter reaches zero, the task is destroyed.</p>
6570
<section id="typeless-methods">
6671
<h2><a href="#typeless-methods">Constructors, destructors, conversion operators</a></h2>
6772
<dl class="m-doc">

‎docs/dependent_async_execution_diagram.png‎

19.5 KB
Loading

0 commit comments

Comments
 (0)