Before updating wavefront.

clin99 · clin99 · commit 9d45bb5b8e9a · 2018-10-19T12:38:33.000-05:00
Merge remote-tracking branch 'refs/remotes/origin/dev' into dev
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/parallel_for.cpp b/doc/cookbook/parallel_for.cpp
diff --git a/doc/cookbook/parallel_for.md b/doc/cookbook/parallel_for.md
@@ -1,14 +1,14 @@
-# Parallelize a For Loop
+# Create a Paralle For-loop Graph
 
 In this tutorial, we are going to demonstrate how to use Cpp-Taskflow
-to run a for loop in parallel.
+to run a for-loop in parallel.
 
-+ [Range-based For Loop](#range-based-for-loop)
-+ [Index-based For Loop](#index-based-for-loop)
++ [Range-based For-loop](#range-based-for-loop)
++ [Index-based For-loop](#index-based-for-loop)
 + [Example 1: Parallel Map](#example-1-parallel-map)
 + [Example 2: Pipeline a Parallel For](#example-2-pipeline-a-parallel-for)
 
-# Range-based For Loop
+# Range-based For-loop
 
 Cpp-Taskflow has a STL-style method `parallel_for` 
 that takes a range of items and applies a callable to each of the item in parallel.
@@ -85,7 +85,7 @@ and would like to enable more efficient parallelization.
 ## Construct the Graph Explicitly
 
 You can explicitly construct a dependency graph that represents a parallel execution 
-of a for loop.
+of a for-loop.
 using only the basic methods `silent_emplace` and `precede`.
 
 
@@ -102,9 +102,9 @@ for(auto item : items) {
 }
 ```
 
-# Index-based For Loop
+# Index-based For-loop
 
-To parallelize a for loop based on index, you can use the capture feature of C++ lambda.
+To parallelize a for-loop based on index, you can use the capture feature of C++ lambda.
 
 ```cpp
  1: auto S = tf.silent_emplace([] () {}).name("S");
diff --git a/doc/cookbook/reduce.cpp b/doc/cookbook/reduce.cpp
diff --git a/doc/cookbook/reduce.md b/doc/cookbook/reduce.md
@@ -1,4 +1,4 @@
-# Reduce a Container of Items in Parallel
+# Create a Parallel Reduction Graph
 
 Parallel tasks normally produce some quantity that needs to be combined or *reduced*
 through particular operations, for instance, sum.
diff --git a/doc/cookbook/task.md b/doc/cookbook/task.md
@@ -1,11 +1,12 @@
-# Understand the Task Construct
+# Understand the Task
 
 In this tutorial, we are going to demonstrate the basic construct of 
 a task dependency graph - *Task*.
 
 + [Create a Task](#create-a-task)
 + [Access the Result of a Task](#access-the-result-of-a-task)
 + [Create Multiple Tasks at One Time](#create-multiple-tasks-at-one-time)
++ [Lifetime of a Task](#lifetime-of-a-task)
 + [Example 1: Create Multiple Dependency Graphs](#example-1-create-multiple-dependency-graphs)
 + [Example 2: Modify Task Attributes](#example-2-modify-task-attributes)
 
@@ -26,11 +27,13 @@ to create a task.
 
 Debrief:
 + Line 1 creates an empty task 
-+ Line 2 creates a task from a given callable object
-+ Line 3 creates a task from a given callable object and returns an additional [std::future][std::future] object for users
++ Line 2 creates a task from a given callable object and returns a task handle
++ Line 3 creates a task from a given callable object and returns, in addition to a task handle,
+  a [std::future][std::future] object for the program
   to access the return value when the task finishes
 
-Each time you create a task, the taskflow object adds a node to the present graph
+Each time you create a task, including an empty one, 
+the taskflow object adds a node to the present graph
 and returns a *task handle* of type `tf::Task`.
 A task handle is a lightweight object
 that wraps up a particular node in a graph
@@ -106,6 +109,18 @@ and create multiple tasks at one time.
 5: );
 ```
 
+# Lifetime of A Task
+
+A task lives with its graph, and is not destroyed until its parent graph
+gets cleaned up.
+A task belongs to only a graph at a time.
+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].
+
+
 ---
 
 # Example 1: Create Multiple Dependency Graphs
@@ -243,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)
 
 ---
 
@@ -96,6 +96,24 @@ tf::Taskflow(N);    // N workers, N+1 threads in the program.
 
 If there is no worker threads in the pool, the master thread will do all the works by itself.
 
+## Q: What is the difference between a Task and a Task Handle?
+
+A task in Cpp-Taskflow is a callable object 
+for which the operation [std::invoke][std::invoke] is applicable.
+It can be either 
+a functor, a lambda expression, a bind expression, 
+or a class objects with `operator()` overloaded.
+
+A task handle is a lightweight object
+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
@@ -143,18 +161,13 @@ for(int i=0; i<N; ++i) {
 tf.wait_for_all();
 ```
 
-## Q: What is a Task?
-
-A `Task` is a lightweight handle associated with an internal graph node
-for users to build task dependencies.
-We do not allow users to explicitly access the internal node but using this wrapper
-to assign different attributes to a graph node.
 
 * * *
 [Github issues]:         https://github.com/cpp-taskflow/cpp-taskflow/issues
 [OpenTimer]:             https://github.com/OpenTimer/OpenTimer
 [README]:                ../README.md
 [C++17]:                 https://en.wikipedia.org/wiki/C%2B%2B17
+[std::invoke]:           https://en.cppreference.com/w/cpp/utility/functional/invoke
 
 
 
diff --git a/doc/home.md b/doc/home.md
@@ -12,11 +12,11 @@ software architecture, C++ API, and library usages.
 
 # Cookbook
 
-+ [Write your First Cpp-Taskflow Program](cookbook/hello_world.md)
-+ [Understand the Task Construct](cookbook/task.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)
-+ [Parallelize a For Loop](cookbook/parallel_for.md)
-+ [Reduce a Container of Items in Parallel](cookbook/reduce.md)
++ [Create a Parallel For-loop Graph](cookbook/parallel_for.md)
++ [Create a Parallel Reduction Graph](cookbook/reduce.md)
 + [Spawn a Task Dependency Graph at Runtime](cookbook/dynamic_tasking.md)
 
 # Application Gallery
diff --git a/example/simple.cpp b/example/simple.cpp
@@ -6,9 +6,9 @@
 #include <taskflow/taskflow.hpp>  // the only include you need
 
 int main(){
-  
-  tf::Taskflow tf(std::thread::hardware_concurrency());
 
+  tf::Taskflow tf;
+  
   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.`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Reduce a Container of Items in Parallel`
	`1`	`+# Create a Parallel Reduction Graph`
`2`	`2`
`3`	`3`	`Parallel tasks normally produce some quantity that needs to be combined or reduced`
`4`	`4`	`through particular operations, for instance, sum.`