updated lifetime in cookbook

tsung-wei-huang · tsung-wei-huang · commit 6806f476e7bb · 2018-10-19T12:29:22.000-05:00
diff --git a/doc/cookbook/a.out b/doc/cookbook/a.out
diff --git a/doc/cookbook/dispatch.md b/doc/cookbook/dispatch.md
@@ -5,12 +5,13 @@ you need to dispatch it to threads for execution
 In this tutorial, we will show you how to execute a 
 task dependency graph.
 
-+ [Graph and Topology](#Graph-and-Topology)
-+ [Blocking Execution](#Blocking-Execution)
-+ [Non-blocking Execution](#Non-blocking-Execution)
-+ [Wait on Topologies](#Wait-on-Topologies)
-+ [Example 1: Multiple Dispatches](#Example-1-Multiple-Dispatches)
-+ [Example 2: Connect Two Dependency Graphs](#Example-2-Connect-Two-Dependency-Graphs)
++ [Graph and Topology](#graph-and-topology)
++ [Blocking Execution](#blocking-execution)
++ [Non-blocking Execution](#non-blocking-execution)
++ [Wait on Topologies](#wait-on-topologies)
++ [Lifetime of a Graph](#lifetime-of-a-graph)
++ [Example 1: Multiple Dispatches](#example-1-multiple-dispatches)
++ [Example 2: Connect Two Dependency Graphs](#example-2-connect-two-dependency-graphs)
 
 # Graph and Topology
 
@@ -138,6 +139,98 @@ After Line 11, there are two topologies in the taskflow object.
 Calling the method `wait_for_topologies` blocks the
 program until both graph complete.
 
+# Lifetime of a Graph
+
+In Cpp-Taskflow, the lifetime of a task sticks with its parent graph.
+The lifetime of a task mostly refers to the user-given callable objects,
+including those captured by a lambda expression.
+When a graph is destroyed, all of its tasks are destroyed.
+Consider the following example that uses 
+[std::shared_ptr][std::shared_ptr] to demonstrate the lifetime of a graph and
+the impact on its task.
+
+```cpp
+ 1: tf::Taskflow tf;
+ 2:
+ 3: auto ptr = std::make_shared<int>(0);
+ 4:
+ 5: std::cout << "reference count before A and B: " << ptr.use_count() << '\n';
+ 6:
+ 7: auto A = tf.silent_emplace([ptr] () {
+ 8:   std::cout << "reference count at A: " << ptr.use_count() << '\n';
+ 9: });
+10:
+11: auto B = tf.silent_emplace([ptr] () {
+12:   std::cout << "reference count at B: " << ptr.use_count() << '\n';
+13: });
+14:
+15: A.precede(B);
+16:
+17: std::cout << "reference count after A and B: " << ptr.use_count() << '\n';
+18:
+19: tf.wait_for_all();
+20:
+21: std::cout << "reference count after A and B: " << ptr.use_count() << '\n';
+```
+
+The output is as follows:
+
+```bash
+reference count before A and B: 1
+reference count after A and B: 3
+reference count at A: 3
+reference count at B: 3
+reference count after A and B: 1
+```
+
+In Line 5, we created a shared pointer object with one reference count on itself.
+After Line 7-13, the reference count increases by two because
+task A and task B both capture a copy of the shared pointer.
+The lifetime of a task has nothing to do with its dependency constraints,
+as shown in Line 8, Line 12, and Line 17.
+However, Line 19 dispatches the graph to threads and cleans up its data structure
+upon finish, including all associated tasks.
+Therefore, the reference count in Line 21 drops down to one (owner at Line 3).
+
+Now let's use the same example but dispatch the graph asynchronously.
+
+```cpp
+ 1: tf::Taskflow tf;
+ 2:
+ 3: auto ptr = std::make_shared<int>(0);
+ 4:
+ 5: std::cout << "reference count before A and B: " << ptr.use_count() << '\n';
+ 6:
+ 7: auto A = tf.silent_emplace([ptr] () {
+ 8:   std::cout << "reference count at A: " << ptr.use_count() << '\n';
+ 9: });
+10:
+11: auto B = tf.silent_emplace([ptr] () {
+12:   std::cout << "reference count at B: " << ptr.use_count() << '\n';
+13: });
+14:
+15: A.precede(B);
+16:
+17: std::cout << "reference count after A and B: " << ptr.use_count() << '\n';
+18:
+19: tf.dispatch().get();  // dispatch the graph without destroying it
+20:
+21: std::cout << "reference count after A and B: " << ptr.use_count() << '\n';
+```
+
+In Line 19, we replace `wait_for_all` with `disaptch` to dispatch the graph asynchronously
+without cleaning up its data structures upon completion.
+In other words, task A and task B remains un-destructed after Line 19,
+and the reference count at this point remains three.
+
+```bash
+reference count before A and B: 1
+reference count after A and B: 3
+reference count at A: 3
+reference count at B: 3
+reference count after A and B: 3
+```
+
 # Example 1: Multiple Dispatches
 
 The example below demonstrates how to create multiple task dependency graphs and 
@@ -253,3 +346,7 @@ The result of the variable `sum` ends up being the summation over
 the integer sequence `[0, 1, 2, ..., 1024)`.
 
 
+* * *
+
+[std::shared_ptr]:  https://en.cppreference.com/w/cpp/memory/shared_ptr
+
diff --git a/doc/cookbook/hello_world.md b/doc/cookbook/hello_world.md
@@ -1,4 +1,4 @@
-# Hello World
+# Write Your First Cpp-Taskflow Program
 
 In this tutorial, we are going to demonstrate how to write a Cpp-Taskflow's
 "hello world" program.
diff --git a/doc/cookbook/task.md b/doc/cookbook/task.md
@@ -118,6 +118,7 @@ The lifetime of a task mostly refers to the user-given callable object,
 including captured values.
 As long as the graph is alive,
 all the associated tasks remain their existence.
+We recommend the users to read [Lifetime of a Graph][Lifetime of a Graph].
 
 
 ---
@@ -257,4 +258,5 @@ Only the latest information will be used.
 [std::function]:         https://en.cppreference.com/w/cpp/utility/functional/function
 [std::invoke]:           https://en.cppreference.com/w/cpp/utility/functional/invoke
 [std::future]:           https://en.cppreference.com/w/cpp/thread/future
+[Lifetime of a Graph]:   dispatch.md#lifetime-of-a-graph
 
diff --git a/doc/faq.md b/doc/faq.md
@@ -3,9 +3,9 @@
 This page summarizes a list of frequently asked questions about Cpp-Taskflow.
 If you cannot find a solution here, please post an issue [here][Github issues].
 
-+ [General Questions](#General-Questions)
-+ [Compilation Issues](#Compilation-Issues)
-+ [Programming Questions](#Programming-Questions)
++ [General Questions](#general-questions)
++ [Compilation Issues](#compilation-issues)
++ [Programming Questions](#programming-questions)
 
 ---
 
@@ -109,6 +109,11 @@ that wraps up a particular node in a graph
 and provides a set of methods for you to assign different attributes to the task
 such as adding dependencies, naming, and assigning a new work.
 
+## Q: What is the Lifetime of a Task and a Graph?
+
+The lifetime of a task sticks with its parent graph. A task is not destroyed until its parent
+graph is destroyed.
+
 ## Q: Is taskflow thread-safe?
 
 No, the taskflow object is not thread-safe. You can't create tasks from multiple threads
diff --git a/doc/home.md b/doc/home.md
@@ -12,7 +12,7 @@ software architecture, C++ API, and library usages.
 
 # Cookbook
 
-+ [Write your First Cpp-Taskflow Program](cookbook/hello_world.md)
++ [Write Your First Cpp-Taskflow Program](cookbook/hello_world.md)
 + [Understand the Task](cookbook/task.md)
 + [Execute a Task Dependency Graph](cookbook/dispatch.md)
 + [Create a Parallel For-loop Graph](cookbook/parallel_for.md)
diff --git a/example/simple.cpp b/example/simple.cpp
@@ -7,8 +7,6 @@
 
 int main(){
   
-  tf::Taskflow tf(std::thread::hardware_concurrency());
-
   auto [A, B, C, D] = tf.silent_emplace(   //  the taskflow graph
     [] () { std::cout << "TaskA\n"; },     //                                 
     [] () { std::cout << "TaskB\n"; },     //          +---+                  

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Hello World`
	`1`	`+# Write Your First Cpp-Taskflow Program`
`2`	`2`
`3`	`3`	`In this tutorial, we are going to demonstrate how to write a Cpp-Taskflow's`
`4`	`4`	`"hello world" program.`