From 079f92e8dafc2e45d7e9865194f2c1df00ced2f9 Mon Sep 17 00:00:00 2001 From: Sean Parent Date: Fri, 7 Jun 2024 10:51:10 -0700 Subject: [PATCH] ** Deleting Examples ** This is cleaning out files under the Hyde 1 directories. Some of these are example files (which likely need a rework, and need to be integrated into CI), and some files contain older docs. I'm marking this commit to refer back to it. --- docs/Gemfile.lock | 10 --- .../stlab/concurrency/await.hpp/index.md | 5 +- .../stlab/concurrency/channel/channel.md | 32 --------- .../concurrency/channel/channel_example.cpp | 46 ------------- .../stlab/concurrency/channel/index.md | 11 --- .../stlab/concurrency/channel/join.md | 30 -------- .../stlab/concurrency/channel/merge.md | 30 -------- .../concurrency/channel/merge_channel.md | 30 -------- .../channel/merge_channel_example.cpp | 59 ---------------- .../concurrency/channel/process/await.md | 18 ----- .../channel/process/await_example.cpp | 66 ------------------ .../concurrency/channel/process/close.md | 13 ---- .../channel/process/close_example.cpp | 69 ------------------- .../concurrency/channel/process/index.md | 46 ------------- .../channel/process/process_example.cpp | 69 ------------------- .../concurrency/channel/process/set_error.md | 16 ----- .../concurrency/channel/process/state.md | 21 ------ .../concurrency/channel/process/yield.md | 13 ---- .../receiver/buffer_size/buffer_size.md | 22 ------ .../buffer_size/buffer_size_example.cpp | 35 ---------- .../channel/receiver/buffer_size/index.md | 12 ---- .../channel/receiver/executor/executor.md | 23 ------- .../receiver/executor/executor_example.cpp | 35 ---------- .../channel/receiver/executor/index.md | 14 ---- .../concurrency/channel/receiver/index.md | 31 --------- .../channel/receiver/operator_pipe.md | 37 ---------- .../receiver/operator_pipe_example.cpp | 42 ----------- .../concurrency/channel/receiver/ready.md | 20 ------ .../concurrency/channel/receiver/set_ready.md | 22 ------ .../channel/receiver/set_ready_example.cpp | 42 ----------- .../channel/sender/call_operator_example.cpp | 44 ------------ .../stlab/concurrency/channel/sender/close.md | 18 ----- .../channel/sender/close_example.cpp | 47 ------------- .../stlab/concurrency/channel/sender/index.md | 19 ----- .../concurrency/channel/sender/operator().md | 28 -------- .../includes/stlab/concurrency/channel/zip.md | 28 -------- .../stlab/concurrency/channel/zip_example.cpp | 50 -------------- .../stlab/concurrency/channel/zip_with.md | 30 -------- .../concurrency/channel/zip_with_example.cpp | 46 ------------- .../default_executor/default_executor.md | 34 --------- .../executor/default_executor/index.md | 15 ---- .../executor/immediate_executor/index.md | 13 ---- .../executor/immediate_executor/operator().md | 15 ---- .../stlab/concurrency/executor/index.md | 9 --- .../executor/main_executor/index.md | 20 ------ .../executor/main_executor/operator().md | 22 ------ .../executor/system_timer/index.md | 21 ------ .../executor/system_timer/operator().md | 39 ----------- .../stlab/concurrency/future/async.md | 24 ------- .../concurrency/future/async_example.cpp | 25 ------- .../stlab/concurrency/future/blocking_get.md | 25 ------- .../stlab/concurrency/future/future/detach.md | 15 ---- .../future/future/detach_example.cpp | 39 ----------- .../stlab/concurrency/future/future/error.md | 15 ---- .../concurrency/future/future/exception.md | 13 ---- .../stlab/concurrency/future/future/future.md | 52 -------------- .../concurrency/future/future/get_try.md | 18 ----- .../stlab/concurrency/future/future/index.md | 33 --------- .../concurrency/future/future/is_ready.md | 13 ---- .../future/future/operator_co_await.md | 27 -------- .../future/operator_co_await_example.cpp | 25 ------- .../future/future/operator_pipe.md | 51 -------------- .../concurrency/future/future/operator_xor.md | 45 ------------ .../concurrency/future/future/recover.md | 49 ------------- .../future/future/recover_example.cpp | 32 --------- .../stlab/concurrency/future/future/reset.md | 13 ---- .../stlab/concurrency/future/future/then.md | 53 -------------- .../future/then_continuation_example.cpp | 20 ------ .../future/future/then_reduction_example.cpp | 29 -------- .../future/future/then_split_example.cpp | 27 -------- .../stlab/concurrency/future/future/valid.md | 13 ---- .../stlab/concurrency/future/index.md | 7 -- .../future/make_exceptional_future.md | 21 ------ .../concurrency/future/make_ready_future.md | 27 -------- .../stlab/concurrency/future/package.md | 23 ------- .../concurrency/future/package_example.cpp | 30 -------- .../stlab/concurrency/future/when_all.md | 38 ---------- .../concurrency/future/when_all_example.cpp | 28 -------- .../future/when_all_void_example.cpp | 45 ------------ .../stlab/concurrency/future/when_any.md | 39 ----------- .../concurrency/future/when_any_example.cpp | 30 -------- .../future/when_any_void_example.cpp | 31 --------- docs/includes/stlab/concurrency/index.md | 18 ++--- .../concurrency/serial_queue/executor().md | 24 ------- .../stlab/concurrency/serial_queue/index.md | 18 ----- .../concurrency/serial_queue/operator().md | 23 ------- .../concurrency/serial_queue/serial_queue.md | 29 -------- .../serial_queue/serial_queue_example.cpp | 39 ----------- docs/includes/stlab/concurrency/task/index.md | 7 -- .../stlab/concurrency/task/operator!=.md | 29 -------- .../stlab/concurrency/task/operator().md | 23 ------- .../stlab/concurrency/task/operator==.md | 30 -------- docs/includes/stlab/concurrency/task/swap.md | 24 ------- .../stlab/concurrency/task/task/index.md | 29 -------- .../stlab/concurrency/task/task/operator=.md | 31 --------- .../concurrency/task/task/operator_bool.md | 21 ------ .../stlab/concurrency/task/task/swap.md | 22 ------ .../stlab/concurrency/task/task/target.md | 29 -------- .../concurrency/task/task/target_type.md | 21 ------ .../stlab/concurrency/task/task/task.md | 65 ----------------- 100 files changed, 14 insertions(+), 2860 deletions(-) delete mode 100644 docs/includes/stlab/concurrency/channel/channel.md delete mode 100644 docs/includes/stlab/concurrency/channel/channel_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/join.md delete mode 100644 docs/includes/stlab/concurrency/channel/merge.md delete mode 100644 docs/includes/stlab/concurrency/channel/merge_channel.md delete mode 100644 docs/includes/stlab/concurrency/channel/merge_channel_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/process/await.md delete mode 100644 docs/includes/stlab/concurrency/channel/process/await_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/process/close.md delete mode 100644 docs/includes/stlab/concurrency/channel/process/close_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/process/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/process/process_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/process/set_error.md delete mode 100644 docs/includes/stlab/concurrency/channel/process/state.md delete mode 100644 docs/includes/stlab/concurrency/channel/process/yield.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/buffer_size/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/executor/executor.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/executor/executor_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/executor/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/operator_pipe.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/operator_pipe_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/ready.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/set_ready.md delete mode 100644 docs/includes/stlab/concurrency/channel/receiver/set_ready_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/sender/call_operator_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/sender/close.md delete mode 100644 docs/includes/stlab/concurrency/channel/sender/close_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/sender/index.md delete mode 100644 docs/includes/stlab/concurrency/channel/sender/operator().md delete mode 100644 docs/includes/stlab/concurrency/channel/zip.md delete mode 100644 docs/includes/stlab/concurrency/channel/zip_example.cpp delete mode 100644 docs/includes/stlab/concurrency/channel/zip_with.md delete mode 100644 docs/includes/stlab/concurrency/channel/zip_with_example.cpp delete mode 100644 docs/includes/stlab/concurrency/executor/default_executor/default_executor.md delete mode 100644 docs/includes/stlab/concurrency/executor/default_executor/index.md delete mode 100644 docs/includes/stlab/concurrency/executor/immediate_executor/index.md delete mode 100644 docs/includes/stlab/concurrency/executor/immediate_executor/operator().md delete mode 100644 docs/includes/stlab/concurrency/executor/index.md delete mode 100644 docs/includes/stlab/concurrency/executor/main_executor/index.md delete mode 100644 docs/includes/stlab/concurrency/executor/main_executor/operator().md delete mode 100644 docs/includes/stlab/concurrency/executor/system_timer/index.md delete mode 100644 docs/includes/stlab/concurrency/executor/system_timer/operator().md delete mode 100644 docs/includes/stlab/concurrency/future/async.md delete mode 100644 docs/includes/stlab/concurrency/future/async_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/blocking_get.md delete mode 100644 docs/includes/stlab/concurrency/future/future/detach.md delete mode 100644 docs/includes/stlab/concurrency/future/future/detach_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/error.md delete mode 100644 docs/includes/stlab/concurrency/future/future/exception.md delete mode 100644 docs/includes/stlab/concurrency/future/future/future.md delete mode 100644 docs/includes/stlab/concurrency/future/future/get_try.md delete mode 100644 docs/includes/stlab/concurrency/future/future/index.md delete mode 100644 docs/includes/stlab/concurrency/future/future/is_ready.md delete mode 100644 docs/includes/stlab/concurrency/future/future/operator_co_await.md delete mode 100644 docs/includes/stlab/concurrency/future/future/operator_co_await_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/operator_pipe.md delete mode 100644 docs/includes/stlab/concurrency/future/future/operator_xor.md delete mode 100644 docs/includes/stlab/concurrency/future/future/recover.md delete mode 100644 docs/includes/stlab/concurrency/future/future/recover_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/reset.md delete mode 100644 docs/includes/stlab/concurrency/future/future/then.md delete mode 100644 docs/includes/stlab/concurrency/future/future/then_continuation_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/then_reduction_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/then_split_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/future/valid.md delete mode 100644 docs/includes/stlab/concurrency/future/index.md delete mode 100644 docs/includes/stlab/concurrency/future/make_exceptional_future.md delete mode 100644 docs/includes/stlab/concurrency/future/make_ready_future.md delete mode 100644 docs/includes/stlab/concurrency/future/package.md delete mode 100644 docs/includes/stlab/concurrency/future/package_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/when_all.md delete mode 100644 docs/includes/stlab/concurrency/future/when_all_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/when_all_void_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/when_any.md delete mode 100644 docs/includes/stlab/concurrency/future/when_any_example.cpp delete mode 100644 docs/includes/stlab/concurrency/future/when_any_void_example.cpp delete mode 100644 docs/includes/stlab/concurrency/serial_queue/executor().md delete mode 100644 docs/includes/stlab/concurrency/serial_queue/index.md delete mode 100644 docs/includes/stlab/concurrency/serial_queue/operator().md delete mode 100644 docs/includes/stlab/concurrency/serial_queue/serial_queue.md delete mode 100644 docs/includes/stlab/concurrency/serial_queue/serial_queue_example.cpp delete mode 100644 docs/includes/stlab/concurrency/task/index.md delete mode 100644 docs/includes/stlab/concurrency/task/operator!=.md delete mode 100644 docs/includes/stlab/concurrency/task/operator().md delete mode 100644 docs/includes/stlab/concurrency/task/operator==.md delete mode 100644 docs/includes/stlab/concurrency/task/swap.md delete mode 100644 docs/includes/stlab/concurrency/task/task/index.md delete mode 100644 docs/includes/stlab/concurrency/task/task/operator=.md delete mode 100644 docs/includes/stlab/concurrency/task/task/operator_bool.md delete mode 100644 docs/includes/stlab/concurrency/task/task/swap.md delete mode 100644 docs/includes/stlab/concurrency/task/task/target.md delete mode 100644 docs/includes/stlab/concurrency/task/task/target_type.md delete mode 100644 docs/includes/stlab/concurrency/task/task/task.md diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock index 134b9254c..46aa5151e 100644 --- a/docs/Gemfile.lock +++ b/docs/Gemfile.lock @@ -1,10 +1,3 @@ -PATH - remote: ../../themes - specs: - jekyll-theme-adobe-hyde (2.0.2) - jekyll (~> 4.3) - jekyll-seo-tag (~> 2.0) - GEM remote: https://rubygems.org/ specs: @@ -67,8 +60,6 @@ GEM rubyzip (>= 1.3.0, < 3.0) jekyll-sass-converter (3.0.0) sass-embedded (~> 1.54) - jekyll-seo-tag (2.8.0) - jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) kramdown (2.4.0) @@ -174,7 +165,6 @@ DEPENDENCIES jekyll-compose jekyll-redirect-from jekyll-remote-theme - jekyll-theme-adobe-hyde! BUNDLED WITH 2.5.11 diff --git a/docs/includes/stlab/concurrency/await.hpp/index.md b/docs/includes/stlab/concurrency/await.hpp/index.md index 92bccebce..af0e3df94 100644 --- a/docs/includes/stlab/concurrency/await.hpp/index.md +++ b/docs/includes/stlab/concurrency/await.hpp/index.md @@ -3,7 +3,10 @@ layout: library title: stlab/concurrency/await.hpp hyde: owner: sean-parent - brief: "Await provides a way to await the value from a future and to notify the default executor that a task is waiting. Blocking calls are discouraged because they may lead to deadlocks or thread explosions.\n\nThere is a good presentation of the issues [here](https://youtu.be/Z86b3Rd09sE).\n" + brief: | + Await provides utilities to synchronously await the value from a `future` and to notify the default executor that a task is waiting. Blocking calls are discouraged because they may lead to deadlocks or thread explosions. + + There is a good presentation of the issues [here](https://youtu.be/Z86b3Rd09sE). tags: - sourcefile library-type: sourcefile diff --git a/docs/includes/stlab/concurrency/channel/channel.md b/docs/includes/stlab/concurrency/channel/channel.md deleted file mode 100644 index bffa4203b..000000000 --- a/docs/includes/stlab/concurrency/channel/channel.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: function -title: stlab::channel -tags: [library] -scope: stlab -pure-name: channel -brief: Creates a pair that consists of a sender and a receiver -annotation: template function -example: channel_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: channel - pure-name: channel - declaration: | - template - std::pair, receiver> channel(E e) - description: This function creates a channel that consists of a sending and a receiving part of the channel. - - name: channel - pure-name: channel - declaration: | - template - receiver channel(E e) - description: This specialization of the channel function creates a channel that consists only of a receiver part. - - kind: parameters - list: - - name: e - description: Executor which is used to send the passed values from the sender down to the receiver. - - kind: result - description: Returns a pair of `sender` - `receiver` of type `T` that form a channel in case that `T` is not of type `void`. In case of type `void` it returns only a channel of type `void`. ---- diff --git a/docs/includes/stlab/concurrency/channel/channel_example.cpp b/docs/includes/stlab/concurrency/channel/channel_example.cpp deleted file mode 100644 index 22c3e4fdf..000000000 --- a/docs/includes/stlab/concurrency/channel/channel_example.cpp +++ /dev/null @@ -1,46 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_bool done{ false }; - - auto hold = receive | [&_done = done](int x) { - cout << x << '\n'; - _done = true; - }; - - // It is necessary to mark the receiver side as ready, when all connections are - // established - receive.set_ready(); - - send(1); - send(2); - send(3); - - // Waiting just for illustrational purpose - while (!done.load()) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} - - -/* - Result: - 1 - 2 - 3 -*/ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/index.md b/docs/includes/stlab/concurrency/channel/index.md deleted file mode 100644 index 6afa9efa4..000000000 --- a/docs/includes/stlab/concurrency/channel/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -layout: library -title: Channels -tags: [library] -brief: This library implements the channel model of interprocess communication. -library-type: library -description: | - [Channels](https://en.wikipedia.org/wiki/Channel_(programming)) are one model of interprocess communication that has its roots in [communicating sequential process](https://en.wikipedia.org/wiki/Communicating_sequential_processes) (CSP). - With channels it is possible to realize processing graphs, that can be used for more than one execution, compared to a graph that is setup with futures. - Channels consist of a sending and a receiving part. Each receiver has an attached process that gets executed when a value is send through. It is possible to split, zip, zip_with, or merge channels. Each processing node is associated with a [process](process/index.html). ---- diff --git a/docs/includes/stlab/concurrency/channel/join.md b/docs/includes/stlab/concurrency/channel/join.md deleted file mode 100644 index 38ad46929..000000000 --- a/docs/includes/stlab/concurrency/channel/join.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: function -title: stlab::join -tags: [library] -scope: stlab -pure-name: join -brief: Creates a future that joins all passed arguments. This function is deprecated and it will soon be removed. Please use instead of `zip_with` -annotation: template function -example: zip_with_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: join - pure-name: join - declaration: | - template - [[deprecated]] auto join(E e, F f, R... upstream_receiver) - description: This function creates a new receiver and attaches the process `f` to it. The values coming from the upstream receiver are the parameters of `f`. The incoming upstream values are not passed one after the other to this process, but they are passed as a complete set of arguments to the process. So the last incoming upstream value triggers the execution of `f`. - - kind: parameters - list: - - name: e - description: Executor which shall be used to execute the task of `f`. - - name: f - description: Callable object that implements the task. Its parameters correspond to the results from the upstream receivers. It is called when all upstream receiver have provided its values. - - name: upstream_receiver - description: The upstream receiver. - - kind: result - description: a future that joins all passed arguments ---- diff --git a/docs/includes/stlab/concurrency/channel/merge.md b/docs/includes/stlab/concurrency/channel/merge.md deleted file mode 100644 index 528826487..000000000 --- a/docs/includes/stlab/concurrency/channel/merge.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: function -title: stlab::merge -tags: [library] -scope: stlab -pure-name: merge -brief: Creates a receiver that merges all passed arguments. This function is deprecated and will be removed soon. Please instead `merge_channel`. -annotation: template function -example: merge_channel_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: merge - pure-name: merge - declaration: | - template - [[deprecated]] auto merge(E e, F f, R... upstream_receiver) - description: This function creates a process that executes the provided function object whenever an upstream process provides a value. There is no defined order in which the process `f` is called with the incoming upstream values. - - kind: parameters - list: - - name: e - description: Executor which is used to schedule the resulting task - - name: f - description: Callable object that implements the process. All results from the upstream process must be convertible to the only argument of the provided function object's function operator or the argument of process' await function. - - name: upstream_receiver - description: The upstream receiver. - - kind: result - description: a receiver that merges all passed arguments ---- diff --git a/docs/includes/stlab/concurrency/channel/merge_channel.md b/docs/includes/stlab/concurrency/channel/merge_channel.md deleted file mode 100644 index 98f428d8e..000000000 --- a/docs/includes/stlab/concurrency/channel/merge_channel.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: function -title: stlab::merge_channel -tags: [library] -scope: stlab -pure-name: merge_channel -brief: Creates a channel that merges all passed arguments -annotation: template function -example: merge_channel_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: merge_channel - pure-name: merge_channel - declaration: | - template - auto merge_channel(E e, F f, R... upstream_receiver) - description: This function creates a receiver with an attached process that executes the by `M`specified merge strategy whenever an upstream process provides a value. `M` can be of type `round_robin_t`, `unordered_t`, or `zip_with`. - - kind: parameters - list: - - name: e - description: Executor which is used to schedule the resulting task - - name: f - description: Callable object that implements the process. All results from the upstream process must be convertible to the only argument of the provided function object's function operator or the argument of process' await function. - - name: upstream_receiver - description: The upstream receiver. - - kind: result - description: a receiver that merges all passed arguments ---- diff --git a/docs/includes/stlab/concurrency/channel/merge_channel_example.cpp b/docs/includes/stlab/concurrency/channel/merge_channel_example.cpp deleted file mode 100644 index 209d2b17b..000000000 --- a/docs/includes/stlab/concurrency/channel/merge_channel_example.cpp +++ /dev/null @@ -1,59 +0,0 @@ -#include -#include -#include - -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send1, send2, send3; - receiver receive1, receive2, receive3; - - tie(send1, receive1) = channel(default_executor); - tie(send2, receive2) = channel(default_executor); - tie(send3, receive3) = channel(default_executor); - - std::atomic_int all_done{0}; - - auto merged = merge_channel( - default_executor, [](int x) { return x; }, receive1, receive2, receive3) | - [&_all_done = all_done](int x) { - cout << x << '\n'; - ++_all_done; - }; - - receive1.set_ready(); - receive2.set_ready(); - receive3.set_ready(); - - send1(1); - send3(3); - send2(2); - send2(5); - send3(6); - send1(4); - - // Waiting just for illustrational purpose - while (all_done < 6) { - invoke_waiting([] { this_thread::sleep_for(std::chrono::milliseconds(1)); }); - } - - pre_exit(); -} - -/* - Result: - - The order of the value is not defined! - - 1 - 3 - 2 - 4 - 5 - 6 -*/ diff --git a/docs/includes/stlab/concurrency/channel/process/await.md b/docs/includes/stlab/concurrency/channel/process/await.md deleted file mode 100644 index 0b94d80a1..000000000 --- a/docs/includes/stlab/concurrency/channel/process/await.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: function -title: await -brief: Called on an await-process whenever a new value was received from upstream. -tags: - - function -example: await_example.cpp -overloads: - void await(T... val): - description: This method is called with the next set of values - arguments: - - description: The value(s) that are passed to `await` - name: val - type: T - return: __OPTIONAL__ - signature_with_names: void await(T... val) ---- -This method is called on an await-process whenever a new value was received from upstream. The type `T` stands here for any semi regular or move-only type. The number of arguments depends on the number of attached upstream sender. Potential state changes from awaitable to yieldable should happen while this method is invoked. diff --git a/docs/includes/stlab/concurrency/channel/process/await_example.cpp b/docs/includes/stlab/concurrency/channel/process/await_example.cpp deleted file mode 100644 index c699b2daf..000000000 --- a/docs/includes/stlab/concurrency/channel/process/await_example.cpp +++ /dev/null @@ -1,66 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -struct sum_2 -{ - process_state_scheduled _state = await_forever; - int _counter = 0; - int _sum = 0; - - void await(int n) { - _sum += n; - ++_counter; - if (_counter == 2) _state = yield_immediate; - } - - int yield() { - _state = await_forever; - auto result = _sum; - _sum = 0; - _counter = 0; - return result; - } - - auto state() const { return _state; } -}; - - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_int r{0}; - - auto hold = receive - | sum_2() - | [&_r = r](int x) { _r = x; }; - - receive.set_ready(); - - send(1); - send(2); - - // Waiting just for illustrational purpose - while (r == 0) { - this_thread::sleep_for(std::chrono::milliseconds(1)); - } - - cout << "The sum is " << r.load() << '\n'; - - pre_exit(); -} - -/* - Result: - - The sum is 3 -*/ diff --git a/docs/includes/stlab/concurrency/channel/process/close.md b/docs/includes/stlab/concurrency/channel/process/close.md deleted file mode 100644 index 19ab5162e..000000000 --- a/docs/includes/stlab/concurrency/channel/process/close.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: close -brief: Called on an await-process whenever the process state is `await_forever` and the incoming queue went dry. -tags: - - function -overloads: - void close(): - description: This method signals the await-process that either the queue of incoming values went dry or an error happened. - return: __OPTIONAL__ - signature_with_names: void close() ---- -This optional method is called on an await-process whenever the process state is `await_forever` and the incoming queue went dry. It is also called when an exception upstream is thrown while calling `await` or `yield` and here no `set_error()` is available. After a `close()`, your process will continue to run so long as your `state()` function returns `yield`. When your `state()` goes to `await`, the process will terminate. \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/process/close_example.cpp b/docs/includes/stlab/concurrency/channel/process/close_example.cpp deleted file mode 100644 index f7355addd..000000000 --- a/docs/includes/stlab/concurrency/channel/process/close_example.cpp +++ /dev/null @@ -1,69 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace stlab; - -struct nop_process -{ - process_state_scheduled _state = await_forever; - - int _v = 0; - - ~nop_process() { std::cout << "nop_process::~nop_process()\n"; } - - void await(int x) { - _v = x; - _state = yield_immediate; - } - - int yield() { - _state = await_forever; - return _v; - } - - auto state() const { return _state; } -}; - -int main() { - sender send; - receiver receive; - std::tie(send, receive) = channel(default_executor); - std::atomic_bool done{ false }; - - auto result = receive | - nop_process{} | - [&_done = done](int v) { - std::cout << "Received " << v << '\n'; - _done = (v > 2); - }; - - receive.set_ready(); - std::cout << "Start sending...\n"; - send(1); - send(2); - send(3); - std::cout << "Closing channel\n"; - send.close(); - - while (!done) { - std::this_thread::sleep_for(std::chrono::milliseconds(1)); - } - std::cout << "Waited till the end.\n"; - - pre_exit(); -} - -/* - Result: - nop_process::~nop_process() - Start sending... - Closing channel - Received 1 - Received 2 - Received 3 - nop_process::~nop_process() - Waited till the end. - */ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/process/index.md b/docs/includes/stlab/concurrency/channel/process/index.md deleted file mode 100644 index 0a1fffe36..000000000 --- a/docs/includes/stlab/concurrency/channel/process/index.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -layout: class -title: process -tags: [library] -ctor: unspecified -dtor: unspecified -annotation: policy class -kind: class -name: process -pure-name: process -brief: Describes a process that gets executed whenever a value is passed into the channel -description: | - The process is a policy that must follow certain rules; it is not a type that the library provides. - - Each channel receiver is associated with a process. The process can either be: - - - an n-ary function object, further here called a _function-process_. - - a type that must have properties, that are described below. It is further here called an _await-process_. - - Since a function-process does not need further explication, the following concentrates on await-processes. - The process accepts values via `await()` as long as the `state()` returns await. If the state changes to yield - then the associated receiver will call `yield()`. - For a further details see the [`state()`](state.html) method. - - It is ensured with a static assert that the process implements a `state() const` method. -example: process_example.cpp ---- - -### Signature of an await-process ### - -Here it is assumed that the process takes `T...`as argument and its result type is `U`. - -~~~ c++ -struct process -{ - void await(T... val); - - U yield(); - - void close(); // optional - - void set_error(std::exception_ptr error); // optional - - process_state_scheduled state() const; -}; -~~~ diff --git a/docs/includes/stlab/concurrency/channel/process/process_example.cpp b/docs/includes/stlab/concurrency/channel/process/process_example.cpp deleted file mode 100644 index 3dee0ef27..000000000 --- a/docs/includes/stlab/concurrency/channel/process/process_example.cpp +++ /dev/null @@ -1,69 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace stlab; - -/* - This process adds all values until a zero is passed as value. - Then it will yield the result and start over again. -*/ - -struct adder -{ - int _sum = 0; - process_state_scheduled _state = await_forever; - - void await(int x) { - _sum += x; - if (x == 0) { - _state = yield_immediate; - } - } - - int yield() { - int result = _sum; - _sum = 0; - _state = await_forever; - return result; - } - - auto state() const { return _state; } -}; - - -int main() { - sender send; - receiver receiver; - std::tie(send, receiver) = channel(default_executor); - - std::atomic_bool done{false}; - - auto calculator = receiver | - adder{} | - [&_done = done](int x) { std::cout << x << '\n'; - _done = true; - }; - - receiver.set_ready(); - - send(1); - send(2); - send(3); - send(0); - - // Waiting just for illustrational purpose - while (!done) { - std::this_thread::sleep_for(std::chrono::milliseconds(1)); - } - - pre_exit(); -} - -/* - Result: - 6 -*/ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/process/set_error.md b/docs/includes/stlab/concurrency/channel/process/set_error.md deleted file mode 100644 index f86c885d9..000000000 --- a/docs/includes/stlab/concurrency/channel/process/set_error.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -layout: function -title: set_error -brief: Called if either on calling `await` or `yield` of the upstream process an exception was thrown. -tags: - - function -overloads: - void set_error(std::exception_ptr ex): - arguments: - - description: The exception pointer of the occurred error - name: ex - type: std::exception_ptr - return: __OPTIONAL__ - signature_with_names: void set_error(std::exception_ptr error) ---- -This optional method is called if either on calling `await` or `yield` on the upstream process an exception was thrown. The pointer of the caught exception is passed. In case that the process does not provide this method, `close`is called instead of. So a process should try to handle its errors within itself. Only errors which occur while passing arguments to the process or retrieving from the process are caught here and then passed to the next downstream process, because this process is not able to handle them. diff --git a/docs/includes/stlab/concurrency/channel/process/state.md b/docs/includes/stlab/concurrency/channel/process/state.md deleted file mode 100644 index 1d38bf393..000000000 --- a/docs/includes/stlab/concurrency/channel/process/state.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: function -title: state -brief: This method must return the current state of the await-process -tags: - - function -overloads: - process_state_scheduled state(): - description: This method must return the state of the process. Subsequent calls without an intermittent `await()`, `close()` or `yield()` must return the same values. Otherwise the result is undefined. - return: the `process_state_scheduled` state - signature_with_names: auto process_state_scheduled state() const ---- - This method must return the current state of the await-process. - - If process_state_scheduled.first is process_state::yield and the timepoint process_state_scheduled.second is in the past, then `yield()` will be called as next action on the process. - - If process_state_scheduled.first is process_state::yield and the timepoint process_state_scheduled.second is in the now or in the future, then a timer will be started that triggers a call to `yield()` when the timer expires. - - If process_state_scheduled.first is process_state::await and the timepoint in process_state_scheduled.second is in the past or now then `yield()` will be called as next action on the process. - - If process_state_scheduled.first is process_state::await and the timepoint in process_state_scheduled.second is in the future, then a timer with this timeout is started. `yield()` will be called when the timer has expired and no new value has arrived. The timer will be cancelled in the later case. diff --git a/docs/includes/stlab/concurrency/channel/process/yield.md b/docs/includes/stlab/concurrency/channel/process/yield.md deleted file mode 100644 index b1b913902..000000000 --- a/docs/includes/stlab/concurrency/channel/process/yield.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: yield -brief: Called on an await-process when it should yield -tags: - - function -overloads: - T yield(): - description: The result of the process. - return: __OPTIONAL__ - signature_with_names: T yield() ---- -This method is called whenever the state has changed from await to yield or a timeout was provided with the recent call to `state()`. diff --git a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size.md b/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size.md deleted file mode 100644 index 7c1657926..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: method -title: stlab::buffer_size -tags: [library] -pure-name: buffer_size -defined-in-header: stlab/concurrency/channel.hpp -declaration: buffer_size() -description: Constructs a new buffer_size object -entities: - - kind: methods - list: - - name: stlab::buffer_size::buffer_size - pure-name: buffer_size - defined-in-header: stlab/concurrency/channel.hpp - declaration: buffer_size(std::size_t sz) - description: Constructs a new buffer_size object and initializes it with the value sz. - - kind: parameters - list: - - name: sz - description: Specifies the size of the buffer -example: buffer_size_example.cpp ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size_example.cpp b/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size_example.cpp deleted file mode 100644 index ad599da2c..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/buffer_size_example.cpp +++ /dev/null @@ -1,35 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace stlab; -using namespace std; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_int v{0}; - - // The order of the process and buffer_size is not relevant, so calling - // times_two & buffer_size{ 2 } would be equivalent - - auto result = receive - | buffer_size{ 2 } & [](int x) { return x * 2; } - | [&v](int x) { v = x; }; - - receive.set_ready(); - - send(1); - - while (v == 0) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} - diff --git a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/index.md b/docs/includes/stlab/concurrency/channel/receiver/buffer_size/index.md deleted file mode 100644 index 9675c2207..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/buffer_size/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: class -title: stlab::buffer_size -tags: [library] -pure-name: buffer_size -dtor: default -name: stlab::buffer_size -defined-in-header: stlab/concurrency/channel.hpp -declaration: struct buffer_size -brief: Encapsulates the buffer size of a process -description: The default size of an incomming queue of each process is 1. In case that one wants to change the queue size of a process, one can realize this by combining a `buffer_size` with a process by using an `operator&` before attaching it to a receiver. `buffer_size` of 0 means no limitation, beside the limitation of available memory. The purpose of the buffer size is flow control between processes. A processes will be allowed to run so long as it is yielding values until the buffer is full before it is suspended. If the processes awaits a value it may be suspended even if the buffer isn't full (if no value is available for the await). A buffer_size of 0 imposes no bounds. The default buffer_size is 1 (a value must be received before a process can yield the next value). ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/executor/executor.md b/docs/includes/stlab/concurrency/channel/receiver/executor/executor.md deleted file mode 100644 index 0a77f42f7..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/executor/executor.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: method -title: stlab::executor -tags: [library] -scope: stlab -pure-name: executor -defined-in-header: stlab/concurrency/channel.hpp -declaration: executor() -brief: Constructs a new executor wrapper object -description: Constructs a new executor wrapper object -entities: - - kind: methods - list: - - name: stlab::executor::executor - pure-name: executor - defined-in-header: stlab/concurrency/channel.hpp - declaration: executor(executor_t e) - description: Constructs a new executor object and stores the given executor in it. - - kind: parameters - list: - - name: e - description: Specifies the executor ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/executor/executor_example.cpp b/docs/includes/stlab/concurrency/channel/receiver/executor/executor_example.cpp deleted file mode 100644 index 0ebe67280..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/executor/executor_example.cpp +++ /dev/null @@ -1,35 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace stlab; -using namespace std; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_int v{0}; - - // The process times_two will be executed immediately - // The order of the process and executor is not relevant so calling - // times_two & executor{ immediate_executor } would be equivalent - auto result = receive - | executor{ immediate_executor } & [](int x) { return x * 2; } - | [&v](int x) { v = x; }; - - receive.set_ready(); - - send(1); - - // Waiting just for illustrational purpose - while (v == 0) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} diff --git a/docs/includes/stlab/concurrency/channel/receiver/executor/index.md b/docs/includes/stlab/concurrency/channel/receiver/executor/index.md deleted file mode 100644 index 691bf3627..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/executor/index.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: class -title: stlab::executor -tags: [library] -scope: stlab -name: executor -pure-name: executor -defined-in-header: stlab/concurrency/channel.hpp -declaration: struct executor -brief: Executor wrapper class -description: This class has only one purpose, to encapsulate an executor to be piped to a `receiver` -dtor: default -example: executor_example.cpp ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/index.md b/docs/includes/stlab/concurrency/channel/receiver/index.md deleted file mode 100644 index 4fce7c6bf..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/index.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: class -title: stlab::receiver -tags: [library] -name: stlab::receiver -pure-name: receiver -defined-in-header: stlab/concurrency/channel.hpp -ctor: default -dtor: default -annotation: template class -declaration: | - template - class receiver -brief: Implements the receiving part of a CSP channel -description: | - Each receiver has an attached process that gets executed when a value is send through the sender into the channel. This attached process must either be an n-ary function object - n depends on the number of attached upstream receiver - or it must be of a type that implements an `await()` and `yield()` method. - - Multiple calls to `operator|` on the same object split the channel. That means that the result of this process is copied into all attached downstream channels. - - The queue size of the attached process can be limited with a `buffer_size`. - - If an exception is thrown while calling the attached process, the exception pointer is passed to the attached process, if it has a `set_error()` method, otherwise this process is closed. - - All non-destructed receivers on a channel must be `set_ready()` or data cannot flow to any - stream processes. - - It is necessary to specialize the template `stlab::smart_test` if type T is e.g. a container of a non copyable type like `std::vector>` so that the the library can correctly dispatch for move-only types internally. This is unfortunately necessary because of a defect in the C++ standard. (The trait std::is_copy_constructible<> does not return the correct results in such a case.) -member-types: - - type: value_type - definition: T ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/operator_pipe.md b/docs/includes/stlab/concurrency/channel/receiver/operator_pipe.md deleted file mode 100644 index d58c5534a..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/operator_pipe.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: method -title: operator| -tags: [library] -scope: receiver -pure-name: operator| -defined-in-header: stlab/concurrency/channel.hpp -declaration: operator|() -brief: Attaches a new process to the channel. -description: Creates a new receiver, attaches the given process as downstream to it and returns this new receiver. The new receiver inherits the executor from its upstream receiver if not an alternative executor is attached. In case that `T` of `receiver` is a move only type, repeated calls of this operator overwrite the previous attached downstream channel. -example: operator_pipe_example.cpp -entities: - - kind: methods - list: - - name: stlab::receiver::operator| - pure-name: operator| - defined-in-header: stlab/concurrency/channel.hpp - declaration: | - template - auto operator|(F&& f) - description: Attaches the given process to the receiver and returns a new receiver. It can either be a function object with a single parameter or a process that has an `await()` and a `yield()` method. L-value processes can be attached when they are wrapped within `std::reference_wrapper`. - - name: stlab::receiver::operator| - pure-name: operator| - defined-in-header: stlab/concurrency/channel.hpp - declaration: | - template - auto operator|(detail::annotated_process&& ap) - description: Attaches the given annotated process to the receiver and returns a new receiver. It can either be a function object with a single parameter or a process that follows this signature. An `annotated_process` should not be explicitly instantiated but it gets implicitly created as soon as one combines a function object with an `operator&` and an `executor` or a `buffer_size` or both. L-value processes can be attached when they are wrapped within `std::reference_wrapper`. - - kind: parameters - list: - - name: f - description: The process to be executed. - - name: args - description: Futures that shall be joined - - kind: result - description: A receiver of type of the result of the passed function object ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/operator_pipe_example.cpp b/docs/includes/stlab/concurrency/channel/receiver/operator_pipe_example.cpp deleted file mode 100644 index 4384d25ac..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/operator_pipe_example.cpp +++ /dev/null @@ -1,42 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace stlab; - -int main() { - sender send; - receiver receive; - - std::tie(send, receive) = channel(default_executor); - - std::atomic_int v{0}; - - // The code demonstrates how a process can be annotated - auto result = receive - | buffer_size{ 3 } & [](int x) { return x * 2; } - | [](int x) { return x * 2; } & buffer_size{ 2 } - | buffer_size{ 3 } & executor{ default_executor } & [](int x) { return x * 2; } - - | executor{ default_executor } & [](int x) { return x + 1; } - | [](int x) { return x + 1; } & executor{ immediate_executor } - | executor{ default_executor } & buffer_size{ 3 } & [](int x) { return x * 2; } - - | [](int x) { return x + 1; } & executor{ default_executor } & buffer_size{ 3 } - | [](int x) { return x * 2; } & buffer_size{ 3 } & executor{ immediate_executor } - - | [&v](int x) { v = x; }; - - receive.set_ready(); - - send(1); - - while (v == 0) { - std::this_thread::sleep_for(std::chrono::milliseconds(1)); - } - - pre_exit(); -} - diff --git a/docs/includes/stlab/concurrency/channel/receiver/ready.md b/docs/includes/stlab/concurrency/channel/receiver/ready.md deleted file mode 100644 index 57f607872..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/ready.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: method -title: ready -tags: [library] -pure-name: ready -defined-in-header: stlab/concurrency/channel.hpp -declaration: ready() -description: Returns `true` if the receiver is ready, otherwise `false`. -entities: - - kind: methods - list: - - name: stlab::receiver::ready - pure-name: ready - defined-in-header: stlab/concurrency/channel.hpp - declaration: bool ready() const - description: Returns `true` if this receiver is ready to receive values. - - kind: result - description: if the receiver was set to ready, it returns `true`, otherwise `false`; the initial value is `false`. - - kind: parameters ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/set_ready.md b/docs/includes/stlab/concurrency/channel/receiver/set_ready.md deleted file mode 100644 index 4a79fd2c8..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/set_ready.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: method -title: set_ready -tags: [library] -scope: receiver -pure-name: set_ready -defined-in-header: stlab/concurrency/channel.hpp -declaration: set_ready -brief: Sets the receiver ready to receive values. -description: Sets the receiver ready to receive values. -example: set_ready_example.cpp -entities: - - kind: methods - list: - - name: stlab::receiver::set_ready - pure-name: set_ready - defined-in-header: stlab/concurrency/channel.hpp - declaration: void set_ready() - description: Sets this receiver ready to receiver values. That implies that no more downstream processes can be attached. - - kind: parameters - - kind: result ---- diff --git a/docs/includes/stlab/concurrency/channel/receiver/set_ready_example.cpp b/docs/includes/stlab/concurrency/channel/receiver/set_ready_example.cpp deleted file mode 100644 index 2452c8f48..000000000 --- a/docs/includes/stlab/concurrency/channel/receiver/set_ready_example.cpp +++ /dev/null @@ -1,42 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_bool done{ false }; - - auto hold = receive | [&_done = done](int x) { - cout << x << '\n'; - _done = true; - }; - - // It is necessary to mark the receiver side as ready, when all connections are - // established - receive.set_ready(); - - send(42); - - // Waiting just for illustrational purpose - while (!done.load()) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} - - -/* - Result: - 42 -*/ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/sender/call_operator_example.cpp b/docs/includes/stlab/concurrency/channel/sender/call_operator_example.cpp deleted file mode 100644 index e13eb567d..000000000 --- a/docs/includes/stlab/concurrency/channel/sender/call_operator_example.cpp +++ /dev/null @@ -1,44 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_bool done{ false }; - - auto hold = receive | [&_done = done](int x) { - cout << x << '\n'; - _done = true; - }; - - receive.set_ready(); - - // calling operator() on send - send(1); - send(2); - send(3); - - // Waiting just for illustrational purpose - while (!done.load()) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} - -/* - Result: - 1 - 2 - 3 -*/ diff --git a/docs/includes/stlab/concurrency/channel/sender/close.md b/docs/includes/stlab/concurrency/channel/sender/close.md deleted file mode 100644 index 71e3f1ef5..000000000 --- a/docs/includes/stlab/concurrency/channel/sender/close.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: method -title: stlab::sender::close -tags: [library] -scope: sender -pure-name: close -defined-in-header: stlab/concurrency/channel.hpp -declaration: close() -description: Close this side of the channel. No more values will be accepted. Already sent value will be processed -entities: - - kind: methods - list: - - name: stlab::sender::close - pure-name: close - defined-in-header: stlab/concurrency/channel.hpp - declaration: void close() - description: Closes this side of the channel, so it is not possible to send new values into it. But it does not destructs the channel. ---- diff --git a/docs/includes/stlab/concurrency/channel/sender/close_example.cpp b/docs/includes/stlab/concurrency/channel/sender/close_example.cpp deleted file mode 100644 index 7ffbc154c..000000000 --- a/docs/includes/stlab/concurrency/channel/sender/close_example.cpp +++ /dev/null @@ -1,47 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send; - receiver receive; - - tie(send, receive) = channel(default_executor); - - std::atomic_bool done{ false }; - - auto hold = receive | [&_done = done](int x) { - cout << x << '\n'; - _done = true; - }; - - receive.set_ready(); - - send(1); - send(2); - send(3); - - // This closes this side of the channel, but all values that were sent - // so far are, are beeing processed - send.close(); - - // Waiting just for illustrational purpose - while (!done.load()) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - pre_exit(); -} - -/* - Result: - 1 - 2 - 3 -*/ diff --git a/docs/includes/stlab/concurrency/channel/sender/index.md b/docs/includes/stlab/concurrency/channel/sender/index.md deleted file mode 100644 index d97b39166..000000000 --- a/docs/includes/stlab/concurrency/channel/sender/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -layout: class -title: stlab::sender -tags: [library] -ctor: default -dtor: default -annotation: template class -name: stlab::sender -pure-name: sender -defined-in-header: stlab/concurrency/channel.hpp -declaration: | - template - class sender -brief: Implements the sending part of a CSP channel -description: -member-types: - - type: value_type - definition: T ---- diff --git a/docs/includes/stlab/concurrency/channel/sender/operator().md b/docs/includes/stlab/concurrency/channel/sender/operator().md deleted file mode 100644 index 4948c60b8..000000000 --- a/docs/includes/stlab/concurrency/channel/sender/operator().md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: method -title: stlab::sender::operator() -tags: [library] -scope: sender -pure-name: operator() -defined-in-header: stlab/concurrency/channel.hpp -declaration: operator() -brief: Sends a new value into the channel -description: Sends a new value into the channel -example: call_operator_example.cpp -entities: - - kind: methods - list: - - name: stlab::sender::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/channel.hpp - declaration: | - template - void operator()(A&&... args) const - description: Sends a new value into the channel. This function never blocks, even if the buffer of the associated reveiver has reached its limits, defined by a `buffer_size`. So even if a limit is given, it will be ignored on an explicit send() and grow the queue however large is required. - - kind: parameters - list: - - name: args - description: The input values of the channel that is defined by this sender - - kind: result ---- - diff --git a/docs/includes/stlab/concurrency/channel/zip.md b/docs/includes/stlab/concurrency/channel/zip.md deleted file mode 100644 index d509a59ba..000000000 --- a/docs/includes/stlab/concurrency/channel/zip.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: function -title: stlab::zip -tags: [library] -scope: stlab -pure-name: zip -brief: It zips the values in step from all upstream receivers. (The functionality has changed after release 1.2.0!) -annotation: template function -example: zip_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: zip - pure-name: zip - declaration: | - template - auto zip(E e, R... upstream_receiver) - description: This function creates receiver of type `tuple` where `T...` are the `result_type`s of the passed `upstream_receiver`. Whenever a complete set of values from each upstream receiver has arrived, it passes the tuple with the values downstream. - - kind: parameters - list: - - name: e - description: Executor which is used to schedule the resulting task - - name: upstream_receiver - description: The upstream receiver(s). - - kind: result - description: a `tuple` where `T...` are the `result_types` of all `upstream_receiver`. ---- diff --git a/docs/includes/stlab/concurrency/channel/zip_example.cpp b/docs/includes/stlab/concurrency/channel/zip_example.cpp deleted file mode 100644 index 48a247a73..000000000 --- a/docs/includes/stlab/concurrency/channel/zip_example.cpp +++ /dev/null @@ -1,50 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send1; - receiver receive1; - sender send2; - receiver receive2; - tie(send1, receive1) = channel(default_executor); - tie(send2, receive2) = channel(default_executor); - - std::atomic_int all_done{ 0 }; - - auto zipped = zip(default_executor, - receive1, - receive2) - | [&_all_done = all_done](std::tuple v) { - cout << get<0>(v) << " " << get<1>(v) << '\n'; - ++_all_done; - }; - - receive1.set_ready(); - receive2.set_ready(); - - // even the values are send in mixed order into the channels, the are passed - // in step order into the zipped process - send1(1); - send2(2.5); - send2(5.7); - send1(4); - - while (all_done < 2) { - this_thread::sleep_for(std::chrono::milliseconds(1)); - } - - pre_exit(); -} - -/* - Result: - 1 2.5 - 4 5.7 -*/ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/channel/zip_with.md b/docs/includes/stlab/concurrency/channel/zip_with.md deleted file mode 100644 index 81e7732a3..000000000 --- a/docs/includes/stlab/concurrency/channel/zip_with.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: function -title: stlab::zip_with -tags: [library] -scope: stlab -pure-name: zip_with -brief: Creates a channel that zips multiple channels into a single one -annotation: template function -example: zip_with_example.cpp -defined-in-header: stlab/concurrency/channel.hpp -entities: - - kind: overloads - list: - - name: zip_with - pure-name: zip_with - declaration: | - template - auto zip_with(E e, F f, R... upstream_receiver) - description: This function creates a new receiver. The values coming from the upstream receiver collected and when from each upstream receiver a values is available, then it passes them to the process `f`. - - kind: parameters - list: - - name: e - description: Executor which shall be used to combine the upstream values. - - name: f - description: The attached process that is invoked with a new set of values. - - name: upstream_receiver - description: The upstream receiver. - - kind: result - description: a `receiver` where `T is the result type of `f` ---- diff --git a/docs/includes/stlab/concurrency/channel/zip_with_example.cpp b/docs/includes/stlab/concurrency/channel/zip_with_example.cpp deleted file mode 100644 index 6d5603aa6..000000000 --- a/docs/includes/stlab/concurrency/channel/zip_with_example.cpp +++ /dev/null @@ -1,46 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - sender send1, send2; - receiver receive1, receive2; - - tie(send1, receive1) = channel(default_executor); - tie(send2, receive2) = channel(default_executor); - - std::atomic_bool done{ false }; - - auto joined = zip_with(default_executor, - [](int x, int y) { return x + y; }, // x will get 1, y will get 2 - receive1, - receive2) - | [&_done = done](int x) { - cout << x << '\n'; - _done = true; - }; - - receive1.set_ready(); - receive2.set_ready(); - - send1(1); - send2(2); - - // Waiting just for illustrational purpose - while (!done) { - this_thread::sleep_for(std::chrono::milliseconds(1)); - } - - pre_exit(); -} - -/* - Result: - 3 -*/ diff --git a/docs/includes/stlab/concurrency/executor/default_executor/default_executor.md b/docs/includes/stlab/concurrency/executor/default_executor/default_executor.md deleted file mode 100644 index 9528ace98..000000000 --- a/docs/includes/stlab/concurrency/executor/default_executor/default_executor.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -layout: function -title: stlab::default_executor -brief: Provides access to a thread pool -defined-in-header: stlab/concurrency/default_executor.hpp -tags: - - function -overloads: - stlab::default_executor(task): - description: Provides access the executor with default priority. - arguments: - - description: The task that shall be executed by this executor - name: f - type: stlab::task - return: __OPTIONAL__ - signature_with_names: default_executor(task f) - stlab::high_executor(task): - description: Provides access the executor with high priority. - arguments: - - description: The task that shall be executed by this executor - name: f - type: stlab::task - return: __OPTIONAL__ - signature_with_names: high_executor(task f) - stlab::low_executor(task): - description: Provides access the executor with low priority. - arguments: - - description: The task that shall be executed by this executor - name: f - type: stlab::task - return: __OPTIONAL__ - signature_with_names: low_executor(task f) ---- -Provides access to the default executor for this process. Normally all instances of this class refer to the same systems thread pool. In case that the operating system does not provide a thread pool, these instances refer to the same custom thread pool. Task submitted to the different instances are executed in the order of the priority high, default and low. Because of performance reasons it cannot be guaranteed that this order is kept strictly. \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/executor/default_executor/index.md b/docs/includes/stlab/concurrency/executor/default_executor/index.md deleted file mode 100644 index 14bba3ee0..000000000 --- a/docs/includes/stlab/concurrency/executor/default_executor/index.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: class -title: stlab::default_executor -tags: - - class -defined-in-header: stlab/concurrency/default_executor.hpp -brief: Interface to the system's thread pool -description: "The stlab.concurrency library provides an abstraction to the OS's system thread pool. It provides its own implementation if the OS does not provide one. \nCurrently the abstraction is available on MacOS, Windows, Emscripten and PNaCl. \nTasks can be submitted with different priority by using the `high_executor`, `default_executor` or `low_executor`. Tasks submitted to the executors are executed in the order of high, default and then low. It is not guaranteed that this order is strictly kept, because of performance reasons." -member-types: - - type: result_type - definition: void - -namespace: - - stlab ---- diff --git a/docs/includes/stlab/concurrency/executor/immediate_executor/index.md b/docs/includes/stlab/concurrency/executor/immediate_executor/index.md deleted file mode 100644 index f0932516e..000000000 --- a/docs/includes/stlab/concurrency/executor/immediate_executor/index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: class -title: stlab::immediate_executor -brief: Executes tasks immediately -tags: - - class -defined-in-header: stlab/concurrency/immediate_executor.hpp -declaration: struct immediate_executor - -member-types: - - type: result_type - definition: void ---- \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/executor/immediate_executor/operator().md b/docs/includes/stlab/concurrency/executor/immediate_executor/operator().md deleted file mode 100644 index 39804ccd8..000000000 --- a/docs/includes/stlab/concurrency/executor/immediate_executor/operator().md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: function -title: operator() -brief: Call operator of this class -defined-in-header: stlab/concurrency/immediate_executor.hpp -overloads: - "template \nvoid operator()(F)": - description: Execute the given task immediately. - arguments: - - description: The task that shall now be executed. - name: f - type: F - signature_with_names: "template \nvoid operator()(F f) const" ---- -Executes the given function on this executor \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/executor/index.md b/docs/includes/stlab/concurrency/executor/index.md deleted file mode 100644 index 7b8d2b680..000000000 --- a/docs/includes/stlab/concurrency/executor/index.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -layout: library -title: Executors -tags: [library] -brief: A collection of executors with different strategies to run tasks. -library-type: library -description: | - Executors provide a means of running functions using different execution policies via a consistent interface. ---- diff --git a/docs/includes/stlab/concurrency/executor/main_executor/index.md b/docs/includes/stlab/concurrency/executor/main_executor/index.md deleted file mode 100644 index 871e76e71..000000000 --- a/docs/includes/stlab/concurrency/executor/main_executor/index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: class -title: stlab::main_executor -tags: [library] -name: stlab::main_executor -pure-name: main_executor -defined-in-header: stlab/concurrency/main_executor.hpp -declaration: struct main_executor -brief: Executes tasks on the application's main loop. -ctor: default -dtor: default -description: | - All tasks that are passed to an instance of this instance are executed in-order on the application's main loop. - - Upon destruction of the main_executor, the underlying main loop is _not_ destroyed. Likewise, all functions submitted to the executor will be executed regardless of destruction state. - So far no main_executor is implemented for Windows. If STLAB_MAIN_EXECUTOR is qt5 or qt6, a main executor is instantiated that executes the tasks on the Qt main loop. -member-types: - - type: result_type - definition: void ---- diff --git a/docs/includes/stlab/concurrency/executor/main_executor/operator().md b/docs/includes/stlab/concurrency/executor/main_executor/operator().md deleted file mode 100644 index 346e769c7..000000000 --- a/docs/includes/stlab/concurrency/executor/main_executor/operator().md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: method -title: stlab::main_executor -tags: [library] -pure-name: operator() -defined-in-header: stlab/concurrency/main_executor.hpp -description: Executes the given function on the application's main loop. -entities: - - kind: methods - list: - - name: stlab::main_executor::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/main_executor.hpp - declaration: | - template - void operator()(F f) const - description: This executors executes the given function object on the applications main loop. - - kind: parameters - list: - - name: f - description: The function object that shall be executed on the main loop. ---- diff --git a/docs/includes/stlab/concurrency/executor/system_timer/index.md b/docs/includes/stlab/concurrency/executor/system_timer/index.md deleted file mode 100644 index 6a7f44fd5..000000000 --- a/docs/includes/stlab/concurrency/executor/system_timer/index.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: class -title: stlab::system_timer -tags: [library] -name: stlab::system_timer -pure-name: system_timer -defined-in-header: stlab/concurrency/system_timer.hpp -declaration: struct system_timer -brief: Executes a function after a specified duration. -ctor: default -dtor: default -description: | - All functions that are passed to an instance of this class are executed after a specified duration. - - [deprecated] All functions that are passed to an instance of this class are executed at the specified time. - - Upon destruction of the system_timer, the underlying main loop is _not_ destroyed. Likewise, all functions submitted to the executor will be executed regardless of destruction state. -member-types: - - type: result_type - definition: void ---- diff --git a/docs/includes/stlab/concurrency/executor/system_timer/operator().md b/docs/includes/stlab/concurrency/executor/system_timer/operator().md deleted file mode 100644 index 9f8a85d9c..000000000 --- a/docs/includes/stlab/concurrency/executor/system_timer/operator().md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: method -title: stlab::system_timer -tags: [library] -pure-name: operator() -defined-in-header: stlab/concurrency/system_timer.hpp -description: | - Executes the given task after the specified duration. - - [deprecated] Executes the given task at the specified time point. - When the time point is in the past, then the task will be executed immediately. - - In case that the previous task takes longer as the time difference between its starting point and the start of the next task. Then the next task may be executed delayed. So a task can be executed later as specified, but never earlier. -entities: - - kind: methods - list: - - name: stlab::system_timer::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/system_timer.hpp - declaration: | - template - [[deprecated]] void operator() (std::chrono::steady_clock::time_point when, F&& f) const - description: This executors executes the given task at the given time. - - name: stlab::system_timer::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/system_timer.hpp - declaration: | - template > - void operator()(std::chrono::duration duration, F f) const - description: This executors executes the given task after the given duration. - - kind: parameters - list: - - name: duration - description: The waiting duration after the task shall be executed. - - name: when - description: The time point when the task shall be executed. - - name: f - description: The task that shall be executed on the given executor. ---- diff --git a/docs/includes/stlab/concurrency/future/async.md b/docs/includes/stlab/concurrency/future/async.md deleted file mode 100644 index e6eb01eeb..000000000 --- a/docs/includes/stlab/concurrency/future/async.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: function -title: stlab::async -brief: Creates a future running on a given executor -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: async_example.cpp -overloads: - "template \nfuture> async(E, F&&, Args&&... )": - description: The template function creates future that runs the callable object f on the specified executor. - arguments: - - description: The executor that shall be used to run the given callable f. - name: executor - type: E - - description: The callable object - name: f - type: F&& - - description: All arguments that are needed to call f, if needed. - name: args - type: Args&& - return: The future on the for the underlying task f - signature_with_names: "template \nfuture> async(E executor, F&& f, Args&&... args)" ---- diff --git a/docs/includes/stlab/concurrency/future/async_example.cpp b/docs/includes/stlab/concurrency/future/async_example.cpp deleted file mode 100644 index 61a7743a2..000000000 --- a/docs/includes/stlab/concurrency/future/async_example.cpp +++ /dev/null @@ -1,25 +0,0 @@ -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto f = async(default_executor, [] { return 42; }); - - // Waiting just for illustration purpose - while (!f.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - cout << "The answer is " << *f.get_try() << "\n"; - - pre_exit(); -} - -/* - Result: - - The answer is 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/blocking_get.md b/docs/includes/stlab/concurrency/future/blocking_get.md deleted file mode 100644 index c5a0d39f8..000000000 --- a/docs/includes/stlab/concurrency/future/blocking_get.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -layout: function -title: stlab::blocking_get -brief: Waits until the future is ready -defined-in-header: stlab/concurrency/utility.hpp -tags: - - function -overloads: - "template\nT blocking_get(future)": - description: Waits as long as the future is fulfilled, or throws the occurred exception. - arguments: - - description: The future on which shall be waited until the result is ready. - name: x - type: future - return: The result of the future x - signature_with_names: template\nT blocking_get(future x) - "void blocking_get(future)": - description: Waits as long as the future is fulfilled, or throws the occurred exception. - arguments: - - description: The future on which shall be waited until the result is ready. - name: x - type: future - signature_with_names: void blocking_get(future x) ---- -Waits until the passed future is ready. Using this function causes that one thread resource is consumed which increases contention and possibly causing a deadlock. As well any subsequent non-dependent calculations on the task are also blocked. It is strongly recommended to avoid using this function, but use continuations. \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/future/future/detach.md b/docs/includes/stlab/concurrency/future/future/detach.md deleted file mode 100644 index 78a110a97..000000000 --- a/docs/includes/stlab/concurrency/future/future/detach.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: function -title: detach -brief: Detaches the associated tasks from this instance. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - void detach(): - description: Lets the current task run and detaches it from this instance. - return: __OPTIONAL__ - signature_with_names: void detach() ---- -Detaches the associated tasks from this instance. So it will be executed even when this instance get destructed. - diff --git a/docs/includes/stlab/concurrency/future/future/detach_example.cpp b/docs/includes/stlab/concurrency/future/future/detach_example.cpp deleted file mode 100644 index 5a3c1f60b..000000000 --- a/docs/includes/stlab/concurrency/future/future/detach_example.cpp +++ /dev/null @@ -1,39 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - atomic_bool done { false }; - { - auto x = async(default_executor, - [] { - this_thread::sleep_for(chrono::seconds(42)); - return 42; } - ); - - auto y = x.then([&_done = done](int x) { - printf("Result %d \n", x); - _done = true; - }); - - y.detach(); - } // The futures x and y are destructed here, but not canceled, - // because the continuation was detached. - - // Waiting just for illustration purpose - while (!done) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} - -/* - Result: - Waiting for 42s... - Result 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/future/error.md b/docs/includes/stlab/concurrency/future/future/error.md deleted file mode 100644 index 1acacbf08..000000000 --- a/docs/includes/stlab/concurrency/future/future/error.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: function -title: error -brief: In case an error occurred, it returns the stored exception pointer. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - std::optional error(): - description: In case an error occurred, it returns the stored exception pointer. - return: __OPTIONAL__ - signature_with_names: "[[deprecated]] std::optional error() const" ---- -Returns a potentially stored exception pointer. This function will be removed in future versions of the library. Use `exception()` instead. - diff --git a/docs/includes/stlab/concurrency/future/future/exception.md b/docs/includes/stlab/concurrency/future/future/exception.md deleted file mode 100644 index 2b4f5c1fe..000000000 --- a/docs/includes/stlab/concurrency/future/future/exception.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: exception -brief: Returns a potentially stored exception pointer. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - std::exception_ptr exception(): - desciption: In case an error occurred, it returns the stored exception pointer. - return: The exception pointer if an exception has occurred. - siganture_with_names: std::exception_ptr exception() const ---- diff --git a/docs/includes/stlab/concurrency/future/future/future.md b/docs/includes/stlab/concurrency/future/future/future.md deleted file mode 100644 index ff880bc36..000000000 --- a/docs/includes/stlab/concurrency/future/future/future.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -layout: function -title: future -brief: Constructs a future -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - future(): - description: The first call to the default constructor will construct an empty future. - return: __OPTIONAL__ - signature_with_names: future() - future(const future &): - description: The copy constructor is available for futures of copyable T and void. It is disabled for move only types - arguments: - - description: __OPTIONAL__ - name: x - type: const future & - return: __OPTIONAL__ - signature_with_names: future(const future& x) - future(future&& ): - description: | - Moves the _target_ of `x` to the target of `*this`. If `x` is _empty_, `*this` - will be _empty_ after the call too. `x` is in a partially formed state after the - call. - arguments: - - description: __OPTIONAL__ - name: x - type: future&& - return: __OPTIONAL__ - signature_with_names: future(future&& x) noexept - future& operator=(const future& ): - description: The copy assignment operator is available for copyable T and void futures. It is disabled for move only types. - arguments: - - description: __OPTIONAL__ - name: x - type: const future& - return: __OPTIONAL__ - signature_with_names: future& operator=(const future& x) - future& operator=(future&& ): - description: | - Moves the _target_ of `x` to the target of `*this`. If `x` is _empty_, `*this` - will be _empty_ after the call too. `x` is in a partially formed state after the - call. - arguments: - - description: __OPTIONAL__ - name: x - type: future&& - return: __OPTIONAL__ - signature_with_names: future& operator=(future&& x) noexept ---- - diff --git a/docs/includes/stlab/concurrency/future/future/get_try.md b/docs/includes/stlab/concurrency/future/future/get_try.md deleted file mode 100644 index affe34fdc..000000000 --- a/docs/includes/stlab/concurrency/future/future/get_try.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: function -title: get_try -brief: Returns the result of the future. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - std::optional get_try(): - description: If `T` is not `void`, it returns an initialized `optional` if the future has succeeded, otherwise an empty `optional`. In case that an error occurred it rethrows the captured exception. - return: __OPTIONAL__ - signature_with_names: std::optional get_try() - bool get_try(): - description: If `T` is void it returns `true` if the future succeeded, otherwise `false`. In case that an error occurred it rethrows the captured exception. - return: __OPTIONAL__ - signature_with_names: bool get_try() ---- -If `T` is of type `void`, it returns `true` if the future is fulfilled; if `T` is a non-`void` type then it returns an `optional` with the result of the future if the future is already fulfilled, otherwise an empty `optional` diff --git a/docs/includes/stlab/concurrency/future/future/index.md b/docs/includes/stlab/concurrency/future/future/index.md deleted file mode 100644 index 93ed9f91c..000000000 --- a/docs/includes/stlab/concurrency/future/future/index.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -layout: class -title: stlab::future -tags: [library] -name: stlab::future -pure-name: future -defined-in-header: stlab/concurrency/future.hpp -dtor: default -annotation: template class -declaration: | - template - class [[nodiscard]] future -brief: An alternative `future` implementation with support for continuations, splits, and joins -description: | - `stlab::future` differs from `std::future` in several ways: - - 1. This future is copyable, so there is no need for a `std::shared_future`. - 1. If this future is only used as an rvalue and there are no copies, then the value (either returned by `get_try` or through a continuation) will be moved. - 1. Multiple continuations - forming a split - may be attached to a single future with `then()`. `then()` is declared `const` since it does not mutate the result object of the future. The continuation is called with the value type, not the future. - 1. A sink argument to a continuation should take the argument by value and move the object as needed. - 1. If the continuation reads the argument it should take it by `const&`. - 1. Behavior of modifying the argument through a non-const reference is undefined (may be a compilation error). - 1. If the last copy of a future destructs, the associated task and any held futures for the task arguments are released and the associated packaged_task will become a no-op if called. - 1. There are no `wait()` or `get()` functions. Instead, there is a `get_try()` which returns an `optional` (or if `T` is `void`, the result is a `bool` with `true` indicating the associated task has executed. - - It is necessary to specialize the template `stlab::smart_test` if type T is e.g. a container of a non copyable type like `std::vector>` so that the the library can correctly dispatch for move-only types internally. This is unfortunately necessary because of a defect in the C++ standard. (The trait std::is_copy_constructible<> does not return the correct results in such a case.) For further details see in ./test/traits_test.cpp. - - ## To Do - - Error handling -member-types: - - type: value_type - definition: T ---- diff --git a/docs/includes/stlab/concurrency/future/future/is_ready.md b/docs/includes/stlab/concurrency/future/future/is_ready.md deleted file mode 100644 index 4f08b24bc..000000000 --- a/docs/includes/stlab/concurrency/future/future/is_ready.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: is_ready -brief: Returns `true` if the future is ready. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - bool is_ready(): - description: Returns `true` if the future is ready, otherwise `false`. - return: __OPTIONAL__ - signature_with_names: bool is_ready() const ---- diff --git a/docs/includes/stlab/concurrency/future/future/operator_co_await.md b/docs/includes/stlab/concurrency/future/future/operator_co_await.md deleted file mode 100644 index 150001bca..000000000 --- a/docs/includes/stlab/concurrency/future/future/operator_co_await.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: function -title: operator co_await -brief: Creates a awaitable object on a given future. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: operator_co_await_example.cpp -overloads: - "template \nauto operator co_await(stlab::future&&)": - description: Creates an awaitable object on a given future of a move-only or copyable type R. - arguments: - - description: The value(s) that are passed to `await` - name: x - type: T - return: __OPTIONAL__ - signature_with_names: "template \nauto operator co_await(stlab::future&& x)" - "auto operator co_await(stlab::future&&)": - description: Creates an awaitable object on a given future of type void. - arguments: - - description: The value(s) that are passed to `await` - name: x - type: T - return: __OPTIONAL__ - signature_with_names: "auto operator co_await(stlab::future&& x)" ---- -This operator converts the given future to an awaitable objects for a coroutine. diff --git a/docs/includes/stlab/concurrency/future/future/operator_co_await_example.cpp b/docs/includes/stlab/concurrency/future/future/operator_co_await_example.cpp deleted file mode 100644 index 6b30acbf4..000000000 --- a/docs/includes/stlab/concurrency/future/future/operator_co_await_example.cpp +++ /dev/null @@ -1,25 +0,0 @@ - -#define STLAB_FUTURE_COROUTINES 1 - -#include - -#include -#include -#include - - -stlab::future get_the_answer() { co_return 42; } - -int main() { - auto f = get_the_answer(); - - std::cout << stlab::blocking_get(f) << '\n'; - - pre_exit(); -} - -/* - Result: - - 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/future/operator_pipe.md b/docs/includes/stlab/concurrency/future/future/operator_pipe.md deleted file mode 100644 index c97c40157..000000000 --- a/docs/includes/stlab/concurrency/future/future/operator_pipe.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -layout: function -title: operator| -brief: Creates a continuation on the current future. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: [then_continuation_example.cpp, then_split_example.cpp] -overloads: - "template \nauto operator|(F&&)": - description: Constructs a continuation with the passed callable object using the same executor as this. - arguments: - - description: | - Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto operator|(F&& f) const" - "template \nauto operator|(F&& f) &&": - description: Constructs a continuation on a r-value with the passed callable object using the same. - arguments: - - description: | - Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: x - type: executor_task_pair - return: __OPTIONAL__ - signature_with_names: "template \nauto operator|(F&& f) &&" - "template \nauto operator|(executor_task_pair)": - description: Constructs a continuation with the passed callable object using the provided executor. - arguments: - - description: | - Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: x - type: executor_task_pair - return: __OPTIONAL__ - signature_with_names: "template \nauto operator|(executor_task_pair x) const" - "template \nauto operator|(executor_task_pair)&&": - description: Constructs a continuation on a r-value with the passed callable object using the provided executor. - arguments: - - description: | - Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: x - type: executor_task_pair - return: __OPTIONAL__ - signature_with_names: "template \nauto operator|(executor_task_pair x) &&" ---- -Creates a new continuation on the current object. - -Multiple `operator|()` invocations on the same future object realize a split. The result of this will be copied into all continuations. - -If `T` of `future` is a move only type, then a split is not possible of course. diff --git a/docs/includes/stlab/concurrency/future/future/operator_xor.md b/docs/includes/stlab/concurrency/future/future/operator_xor.md deleted file mode 100644 index 3c4bb7c8d..000000000 --- a/docs/includes/stlab/concurrency/future/future/operator_xor.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -layout: function -title: operator^ -brief: Creates a recoverable future on the current object. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: recover_example.cpp -overloads: - "template \nauto operator^(F&& f)": - description: Constructs a recoverable continuation that gets a `future` passed. - arguments: - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto operator^(F&& f) const" - "template \nauto operator^(F&& f)&&": - description: Constructs a recoverable continuation that gets a `future` passed. - arguments: - - description: Constructs a recoverable continuation on an r-value future. It gets a `future` passed. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto operator^(F&& f) &&" - "template \nauto operator^(executor_task_pair)": - description: Constructs a recoverable continuation that gets a `future` passed. It uses the provided executor. - arguments: - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: x - type: executor_task_pair - return: __OPTIONAL__ - signature_with_names: "template \nauto operator^(executor_task_pair x) const" - "template \nauto operator^(executor_task_pair)&&": - description: Constructs a continuation on a r-value with the passed callable object using the provided executor. - arguments: - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: x - type: executor_task_pair - return: __OPTIONAL__ - signature_with_names: "template \nauto operator^(executor_task_pair x) &&" ---- -Since the futures are value based, the recover method should be used to do the error handling. Its functionality is identical to `.recover()`. - - diff --git a/docs/includes/stlab/concurrency/future/future/recover.md b/docs/includes/stlab/concurrency/future/future/recover.md deleted file mode 100644 index ff5564b2c..000000000 --- a/docs/includes/stlab/concurrency/future/future/recover.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -layout: function -title: recover -brief: Creates a recoverable future on the current object. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: recover_example.cpp -overloads: - "template \nauto recover(F&& f)": - description: Constructs a recoverable continuation that gets a `future` passed. It uses the same executor as this. - arguments: - - description: Callable object that implements the `recover()` function. Its parameter must be of type of this `future` instance. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto recover(F&& f) const" - "template \nauto recover(F&& f)&&": - description: Constructs a recoverable continuation on an r-value future. It gets a `future` passed. It uses the same executor as this. - arguments: - - description: Callable object that implements the `recover()` function. Its parameter must be of type of this `future` instance. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto recover(F&& f) &&" - "template \nauto recover(E executor, F&& f)": - description: Constructs a recoverable continuation that gets a `future` passed. It uses the provided executor. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the `recover()` function. Its parameter must be of type of this `future` instance. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto recover(E executor, F&& f) const" - "template \nauto recover(E executor, F&& f)&&": - description: Constructs a recoverable continuation on an r-value future. It gets a `future` passed. It uses the the provided executor. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the `recover()` function. Its parameter must be of type of this `future` instance. - name: f - type: F - return: __OPTIONAL__ - signature_with_names: "template \nauto recover(E executor, F&& f) &&" ---- -Since the futures are value based, the recover method should be used to do the error handling. diff --git a/docs/includes/stlab/concurrency/future/future/recover_example.cpp b/docs/includes/stlab/concurrency/future/future/recover_example.cpp deleted file mode 100644 index cd9438283..000000000 --- a/docs/includes/stlab/concurrency/future/future/recover_example.cpp +++ /dev/null @@ -1,32 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto x = async(default_executor, [] { - throw runtime_error("Vogons did arrive!"); - return 42; - }); - - auto r = x.recover([](future f) { - try { - auto answer = *f.get_try(); - cout << "The answer is " << answer << '\n'; - } - catch (const exception& ex) { - cout << "The error \"" << ex.what() << "\" happened!\n"; - } - }); - - // Waiting just for illustration purpose - while (!r.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} - -// Result: The error "Vogons did arrive!" happened! diff --git a/docs/includes/stlab/concurrency/future/future/reset.md b/docs/includes/stlab/concurrency/future/future/reset.md deleted file mode 100644 index df7c44e40..000000000 --- a/docs/includes/stlab/concurrency/future/future/reset.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: reset -brief: Cancels this future -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - void reset(): - description: Cancels this future. If the task is already running, its result will be abandoned and no subsequent continuation will be started. - return: __OPTIONAL__ - signature_with_names: void reset() ---- diff --git a/docs/includes/stlab/concurrency/future/future/then.md b/docs/includes/stlab/concurrency/future/future/then.md deleted file mode 100644 index 616661a14..000000000 --- a/docs/includes/stlab/concurrency/future/future/then.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -layout: function -title: then -brief: Creates a continuation on the current future. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: [then_continuation_example.cpp, then_split_example.cpp] -overloads: - "template \nauto then(F&&) const": - description: Constructs a continuation with the passed callable object using the same executor as this. - arguments: - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: a future of the type of the result type of the passed function object. - signature_with_names: "template \nauto then(F&&) const" - "template \nauto then(F&&) &&": - description: Constructs a continuation on a r-value with the passed callable object using the same executor as this. - arguments: - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: a future of the type of the result type of the passed function object. - signature_with_names: "template \nauto then(F&&) &&" - "template \nauto then(E, F&&) const": - description: Constructs a continuation with the passed callable object using the same executor as this. - arguments: - - description: Executor which is used to schedule the resulting task. - name: executor - type: E - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: a future of the type of the result type of the passed function object. - signature_with_names: "template \nauto then(E executor, F&& f) const" - "template \nauto then(E, F&&) &&": - description: Constructs a continuation on a r-value with the passed callable object using the same executor as this. - arguments: - - description: Executor which is used to schedule the resulting task. - name: executor - type: E - - description: Callable object that implements the continuation. `T` of this must be convertible to the parameter of `f`. - name: f - type: F - return: a future of the type of the result type of the passed function object. - signature_with_names: "template \nauto then(E executor, F&& f) &&" ---- -Creates a new continuation on the current object. - -Multiple `then()` invocations on the same future object realize a split. The result of this will be copied into all continuations. - -If `T` of `future` is a move only type, then a split is not possible of course. \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/future/future/then_continuation_example.cpp b/docs/includes/stlab/concurrency/future/future/then_continuation_example.cpp deleted file mode 100644 index 259e0e4fa..000000000 --- a/docs/includes/stlab/concurrency/future/future/then_continuation_example.cpp +++ /dev/null @@ -1,20 +0,0 @@ -#include -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto x = async(default_executor, [] { return 42; }); - - auto y = x.then([](int x) { printf("Result %d \n", x); }); - - // Waiting just for illustration purpose - while (!y.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} - -// Result: Result 42 diff --git a/docs/includes/stlab/concurrency/future/future/then_reduction_example.cpp b/docs/includes/stlab/concurrency/future/future/then_reduction_example.cpp deleted file mode 100644 index 13895029f..000000000 --- a/docs/includes/stlab/concurrency/future/future/then_reduction_example.cpp +++ /dev/null @@ -1,29 +0,0 @@ - -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - future a = async(default_executor, [] { cout << 1 << "\n"; return 42; }).then([] (auto x) { - return async(default_executor, [] (auto x) { cout << 2 << "\n"; return x + 42; }, x); - }); - - while (!a.get_try()) { - this_thread::sleep_for(chrono::milliseconds(1)); - } - - cout << *a.get_try() << '\n'; - - pre_exit(); -} -/* - Result: - 1 - 2 - 84 -*/ \ No newline at end of file diff --git a/docs/includes/stlab/concurrency/future/future/then_split_example.cpp b/docs/includes/stlab/concurrency/future/future/then_split_example.cpp deleted file mode 100644 index cf40fa537..000000000 --- a/docs/includes/stlab/concurrency/future/future/then_split_example.cpp +++ /dev/null @@ -1,27 +0,0 @@ -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto x = async(default_executor, [] { return 42; }); - - auto c1 = x.then([](int x) { printf("Split A %d \n", x); }); - auto c2 = x.then([](int x) { printf("Split B %d \n", x); }); - - // Waiting just for illustration purpose - while (!c1.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - while (!c2.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} -/* - Result: (Note: The order of the results is not defined.) - - Split B 42 - Split A 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/future/valid.md b/docs/includes/stlab/concurrency/future/future/valid.md deleted file mode 100644 index 7db9cdbe8..000000000 --- a/docs/includes/stlab/concurrency/future/future/valid.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -layout: function -title: valid -brief: Returns `true` if the future is valid. -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - bool valid(): - description: Returns `true` if the future is connected with a valid task. A default constructed object or a canceled one returns `false`. - return: returns `true` if the future has an associated function object, otherwise `false`; after a reset, it returns `false` - signature_with_names: bool valid() const ---- diff --git a/docs/includes/stlab/concurrency/future/index.md b/docs/includes/stlab/concurrency/future/index.md deleted file mode 100644 index bf4d379a5..000000000 --- a/docs/includes/stlab/concurrency/future/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: library -title: Futures -tags: [library] -brief: Futures class and related functions -library-type: library ---- diff --git a/docs/includes/stlab/concurrency/future/make_exceptional_future.md b/docs/includes/stlab/concurrency/future/make_exceptional_future.md deleted file mode 100644 index 4cf2b2afe..000000000 --- a/docs/includes/stlab/concurrency/future/make_exceptional_future.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: function -title: stlab::make_exceptional_future -brief: Creates a future that is fulfilled as failed -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - "template \nfuture make_exceptional_future(std::exception_ptr, E)": - description: This function creates a future that is fulfilled as failed. - arguments: - - description: The exception pointer - name: exception - type: std::exception_ptr - - description: The executor that will be used for an attached continuation - name: executor - type: E - return: A future that is ready in an error state. - signature_with_names: "template \nfuture make_exceptional_future(std::exception_ptr exception, E executor)" ---- -Creates a future that is fulfilled as failed diff --git a/docs/includes/stlab/concurrency/future/make_ready_future.md b/docs/includes/stlab/concurrency/future/make_ready_future.md deleted file mode 100644 index 7752226f7..000000000 --- a/docs/includes/stlab/concurrency/future/make_ready_future.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: function -title: stlab::make_ready_future -brief: Creates a future that is already fulfilled -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -overloads: - "template \nfuture make_ready_future(T&&, E)": - description: This function creates a future that is already fulfilled. - arguments: - - description: The result value of the future - name: x - type: T&& - - description: The executor that will be used for an attached continuation - name: executor - type: E - signature_with_names: "template \nfuture make_ready_future(T&& x, E executor)" - "template \nfuture make_ready_future(E)": - description: This function creates a future that is already fulfilled. - arguments: - - description: The executor that will be used for an attached continuation - name: executor - type: E - signature_with_names: "template \nfuture make_ready_future(E executor)" ---- -Creates a future that is already fulfilled diff --git a/docs/includes/stlab/concurrency/future/package.md b/docs/includes/stlab/concurrency/future/package.md deleted file mode 100644 index 588a2b427..000000000 --- a/docs/includes/stlab/concurrency/future/package.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: function -title: stlab::package -brief: Create a promise/future pair -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: package_example.cpp -overloads: - "template \nauto package(E executor, F f)": - description: The template function package creates a pair of a promise and a future. Calling the promise will be invoked immediately, not on the provided `executor`. The purpose of the passed `executor` is to have already an executor for an attached continuation. - If the promise is destructed and have not been called, then the associated future contains a std::exception with the error code `stlab::broken_promise`. - arguments: - - description: The executor is the default executor for a possible attached continuation - name: executor - type: E - arguments: - - description: Callable object to call - name: f - type: F - return: A std::pair of a promise and the associated future. - signature_with_names: "template \nauto package(E executor, F f)" ---- diff --git a/docs/includes/stlab/concurrency/future/package_example.cpp b/docs/includes/stlab/concurrency/future/package_example.cpp deleted file mode 100644 index 05d71c11d..000000000 --- a/docs/includes/stlab/concurrency/future/package_example.cpp +++ /dev/null @@ -1,30 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto p = package(default_executor, [](int x) { return x+x; }); - auto packagedTask = p.first; - auto f = p.second; - - packagedTask(21); - - // Waiting just for illustration purpose - while (!f.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - cout << "The answer is " << *f.get_try() << "\n"; - - pre_exit(); -} - -/* - Result: - - The answer is 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/when_all.md b/docs/includes/stlab/concurrency/future/when_all.md deleted file mode 100644 index f3bb950eb..000000000 --- a/docs/includes/stlab/concurrency/future/when_all.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -layout: function -title: stlab::when_all -brief: Creates a joining future -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: [ when_all_example.cpp, when_all_void_example.cpp ] -overloads: - "template \nauto when_all(E, F, future...)": - description: This function create a joining future. When all passed `args` futures are fulfilled, then the continuation tasks defined with `f` is scheduled on the executor `executor`. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the continuing task - name: f - type: F - - description: Callable object that implements the continuing task - name: args - type: future... - return: The continuation on the group of passed futures. - signature_with_names: "template \nauto when_all(E executor, F f, future... args)" - "template \nauto when_all(E, F, std::pair)": - description: This function create a joining future out of the given range. In case that it is a range of futures of move-only types, the futures are moved internally out of the range into the function. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the continuing task - name: f - type: F - - description: Callable object that implements the continuing task - name: range - type: std::pair - return: The continuation on the group of passed futures. - signature_with_names: "template \nauto when_all(E executor, F f, std::pair range)" ---- diff --git a/docs/includes/stlab/concurrency/future/when_all_example.cpp b/docs/includes/stlab/concurrency/future/when_all_example.cpp deleted file mode 100644 index d874ca746..000000000 --- a/docs/includes/stlab/concurrency/future/when_all_example.cpp +++ /dev/null @@ -1,28 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto argument1 = async(default_executor, [] { return 42; }); - auto argument2 = async(default_executor, [] { return string("The answer is"); }); - - auto result = when_all(default_executor, [](int answer, std::string text) { - cout << text << " " << answer << '\n'; - }, argument1, argument2); - - // Waiting just for illustration purpose - while (!result.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} - -/* - Result: - - The answer is 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/when_all_void_example.cpp b/docs/includes/stlab/concurrency/future/when_all_void_example.cpp deleted file mode 100644 index 4f28fd13e..000000000 --- a/docs/includes/stlab/concurrency/future/when_all_void_example.cpp +++ /dev/null @@ -1,45 +0,0 @@ -#include -#include -#include -#include -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto fv = []{ - return stlab::make_ready_future(immediate_executor); - }; - auto fi = []{ - return stlab::make_ready_future(42, immediate_executor); - }; - auto fs = []{ - return stlab::make_ready_future("Hello, world!", immediate_executor); - }; - auto fb = []{ - return stlab::make_ready_future(true, immediate_executor); - }; - - auto f = when_all(stlab::default_executor, [](auto... args){ - for_each_argument([](auto x) { cout << x << "\n"; }, args...); - }, fi(), fv(), fs(), fv(), fb(), fv()); - - while (!f.get_try()) std::this_thread::sleep_for(std::chrono::milliseconds(1)); - - pre_exit(); -} - -/* - Result: - - 42 - Hello, world! - 1 - or: - 1 - Hello, world! - 42 -*/ diff --git a/docs/includes/stlab/concurrency/future/when_any.md b/docs/includes/stlab/concurrency/future/when_any.md deleted file mode 100644 index 43f6d0a9f..000000000 --- a/docs/includes/stlab/concurrency/future/when_any.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -layout: function -title: stlab::when_any -brief: Creates a future that continues on the first success of any futures passed -defined-in-header: stlab/concurrency/future.hpp -tags: - - function -example: [ when_any_example.cpp, when_any_void_example.cpp ] -overloads: - "template \nauto when_any(E, F, future...)": - description: This function create a future that continues whenever the first future of the passed arguments `args` succeeds. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the continuing task - name: f - type: F - - description: Callable object that implements the continuing task - name: args - type: future... - return: The continuation on the group of passed futures. - signature_with_names: "template \nauto when_any(E executor, F f, future... args)" - "template \nauto when_any(E, F, std::pair)": - description: This function create a future that continues whenever the first future within the range succeeds. In case that it is a range of futures of move-only types, the futures are moved internally out of the range into the function. - arguments: - - description: Executor which is used to schedule the resulting task - name: executor - type: E - - description: Callable object that implements the continuing task - name: f - type: F - - description: This describes the range of futures. If an empty range is provided then an stlab::future_exception with code stlab::future_errc::broken_promise is thrown. - name: range - type: std::pair - return: The continuation on the group of passed futures. - signature_with_names: "template \nauto when_all(E executor, F f, std::pair range)" ---- -Creates a future that continues on the first success of any futures passed. The results of all passed futures must be convertible to the first parameter of the continuing function. The function must accept the a second parameter of std::size_t. It will receive the index of the future that succeeded first. diff --git a/docs/includes/stlab/concurrency/future/when_any_example.cpp b/docs/includes/stlab/concurrency/future/when_any_example.cpp deleted file mode 100644 index c70dc2922..000000000 --- a/docs/includes/stlab/concurrency/future/when_any_example.cpp +++ /dev/null @@ -1,30 +0,0 @@ -#include -#include -#include -#include -#include - -using namespace std; -using namespace stlab; - -int main() { - auto argument1 = async(default_executor, [] { return 42; }); - auto argument2 = async(default_executor, [] { return 815; }); - - auto result = when_any(default_executor, [](int x, std::size_t index) { - cout << "The current result is " << x << " " << index << '\n'; - }, argument1, argument2); - - // Waiting just for illustration purpose - while (!result.get_try()) { this_thread::sleep_for(chrono::milliseconds(1)); } - - pre_exit(); -} - -/* - Result: - - The current result is 42 0 - or - The current result is 815 1 -*/ diff --git a/docs/includes/stlab/concurrency/future/when_any_void_example.cpp b/docs/includes/stlab/concurrency/future/when_any_void_example.cpp deleted file mode 100644 index 438dec879..000000000 --- a/docs/includes/stlab/concurrency/future/when_any_void_example.cpp +++ /dev/null @@ -1,31 +0,0 @@ -#include -#include -#include -#include -#include -#include -#include - - -using namespace std; -using namespace stlab; - -int main() { - auto fv = []{ - return stlab::make_ready_future(immediate_executor); - }; - - auto f = when_any(stlab::default_executor, [](size_t index){ - std::cout << "f: " << index << '\n'; - }, fv(), fv(), fv(), fv(), fv(), fv()); - - while (!f.get_try()) std::this_thread::sleep_for(std::chrono::milliseconds(1)); - - pre_exit(); -} - -/* - Result: (index number may vary) - - f: 0 -*/ diff --git a/docs/includes/stlab/concurrency/index.md b/docs/includes/stlab/concurrency/index.md index bb463efef..0ddb284e1 100644 --- a/docs/includes/stlab/concurrency/index.md +++ b/docs/includes/stlab/concurrency/index.md @@ -3,22 +3,24 @@ layout: directory title: concurrency hyde: owner: sean-parent - brief: This library provides high level abstractions for implementing algorithms that eases the use of multiple CPU cores while minimizing the contention. + brief: This library provides high-level abstractions for implementing algorithms that ease using multiple CPU cores while minimizing contention. description: | - The future implementation differs in several aspects compared to the C++11/14/17 standard futures: - It provides continuations and joins, which were just added in a C++17 TS. But more important this futures propagate values through the graph and not futures. This allows an easy way of creating splits. That means a single future can have multiple continuations into different directions. + The `stlab::future` implementation differs in several aspects from the C++11/14/17 `std::future`: - An other important difference is that the futures support cancellation. So if one is not anymore interested in the result of a future, then one can destroy the future without the need to wait until the future is fulfilled, as it is the case with `std::future` (and `boost::future`). An already started future will run until its end, but will not trigger any continuation. So in all these cases, all chained continuations will never be triggered. Additionally the future interface is designed in a way, that one can use build in or custom build executors. - This implies too, that the user has to take more care, that all references used inside the task associated with the future must either exist, or their meanwhile absence must be taken into account. (One appropriate mechanism here are weak and shared pointer.) + - Provides continuations (`then`) and joins (`when_all` and `when_any`). + - Support splitting by attaching multiple continuations to a single `future.` + - Automatically cancel any uniquely contributing tasks when a `future` is destroyed. + - Supports custom executors. + - Auto-reduces, i.e., a `future>` is automatically converted to a `future`. - Since one can create with futures only graphs for single use, this library provides as well channels. With these channels one can build graphs, that can be used for multiple invocations. + The library provides a default executor that uses the system thread pool, if available. Otherwise, it uses a portable, high-performance, elastic, task-stealing executor. The library also provides a number of utilities and experimental features. --- ### Requirements -- C++17 compliant compiler (clang, gcc 7, Visual Studio 2017) -- boost 1.60.0 (optional, variant, if they are not available from the compiler and test for executing the UnitTests) +- C++17 compliant compiler (clang, gcc, Visual Studio) +- boost (for executing the unit tests) ### Authors diff --git a/docs/includes/stlab/concurrency/serial_queue/executor().md b/docs/includes/stlab/concurrency/serial_queue/executor().md deleted file mode 100644 index a11c23358..000000000 --- a/docs/includes/stlab/concurrency/serial_queue/executor().md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: method -title: stlab::serial_queue::executor -tags: [library] -scope: serial_queue -pure-name: executor -defined-in-header: stlab/concurrency/serial_queue.hpp -brief: Constructs an executor from the serial queue -entities: - - kind: methods - list: - - name: stlab::serial_queue::executor - pure-name: executor - defined-in-header: stlab/concurrency/serial_queue.hpp - declaration: | - auto executor() const - description: Projects the serial queue into an executor. - - kind: result - description: An executor that serializes execution of tasks. ---- - -Like other executors, this routine returns an executor whose `operator()` returns `void`. As such, the tasks enqueued to the serial queue this way are not cancelable, nor is there a future through which their results are returned. - -This is a good means of passing "fire and forget" tasks into the serial queue. diff --git a/docs/includes/stlab/concurrency/serial_queue/index.md b/docs/includes/stlab/concurrency/serial_queue/index.md deleted file mode 100644 index 4474d108e..000000000 --- a/docs/includes/stlab/concurrency/serial_queue/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: class -title: stlab::serial_queue -tags: [library] -scope: stlab -pure-name: serial_queue -defined-in-header: stlab/concurrency/serial_queue.hpp -dtor: default -annotation: template class -example: serial_queue_example.cpp -declaration: | - template - class serial_queue -brief: An executor wrapper that causes enqueued tasks to be run serially. -member-types: - - type: executor_t - definition: E ---- diff --git a/docs/includes/stlab/concurrency/serial_queue/operator().md b/docs/includes/stlab/concurrency/serial_queue/operator().md deleted file mode 100644 index 1ec131731..000000000 --- a/docs/includes/stlab/concurrency/serial_queue/operator().md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: method -title: stlab::serial_queue::operator() -tags: [library] -scope: serial_queue -pure-name: operator() -defined-in-header: stlab/concurrency/serial_queue.hpp -brief: Passes the task to the serial_queue for scheduling and execution -entities: - - kind: methods - list: - - name: stlab::serial_queue::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/serial_queue.hpp - declaration: | - template - auto operator()(F&& f, Args&&... args) - description: Pass a task to the serial_queue for execution - - kind: result - description: Returns a future that will contain the result of the executed task. ---- - -The `stlab::future` returned by this routine must be retained, or the task it is associated with will be cancelled if it has not already been executed. diff --git a/docs/includes/stlab/concurrency/serial_queue/serial_queue.md b/docs/includes/stlab/concurrency/serial_queue/serial_queue.md deleted file mode 100644 index 3ac211cdd..000000000 --- a/docs/includes/stlab/concurrency/serial_queue/serial_queue.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: method -title: stlab::serial_queue::serial_queue -tags: [library] -scope: serial_queue -pure-name: serial_queue -defined-in-header: stlab/concurrency/serial_queue.hpp -brief: Constructs a serial_queue -entities: - - kind: methods - list: - - name: stlab::serial_queue::serial_queue - pure-name: serial_queue - defined-in-header: stlab/concurrency/serial_queue.hpp - declaration: | - template - explicit serial_queue_t(Executor e, schedule_mode mode = schedule_mode::single) - description: Constructs the serial queue backed by the passed executor and using the supplied schedule mode. - - kind: parameters - list: - - name: e - description: The executor the serial queue will use to run tasks - - name: mode - description: | - Specify the mode by which the serial queue runs tasks: - - - `schedule_mode::single` — Yield to the executor between runs of individual tasks. This mode is preferrable if you are expecting tasks to take a long amount of time. - - `schedule_mode::all` — Yield to the executor once all tasks available at the start of processing have been run. This mode is preferrable if you are expecting tasks to take a short amount of time. ---- diff --git a/docs/includes/stlab/concurrency/serial_queue/serial_queue_example.cpp b/docs/includes/stlab/concurrency/serial_queue/serial_queue_example.cpp deleted file mode 100644 index a729e6a2f..000000000 --- a/docs/includes/stlab/concurrency/serial_queue/serial_queue_example.cpp +++ /dev/null @@ -1,39 +0,0 @@ -#include -#include -#include - -#include -#include - -using namespace std; -using namespace stlab; - -serial_queue_t ioq(default_executor); - -void say_hello(string to_whom) { - ioq.executor()([_whom = move(to_whom)](){ - cout << "Hello, " << _whom << "!\n"; - }); -} - -int main(int, char**) { - say_hello("fella"); - say_hello("chief"); - say_hello("pal"); - say_hello("world"); - - auto done = ioq([]{}); - - while (!done.get_try()) { } - - pre_exit(); -} - -/* - Result: - - Hello, fella! - Hello, chief! - Hello, pal! - Hello, world! -*/ diff --git a/docs/includes/stlab/concurrency/task/index.md b/docs/includes/stlab/concurrency/task/index.md deleted file mode 100644 index cb05c3ab0..000000000 --- a/docs/includes/stlab/concurrency/task/index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -layout: library -title: Task -tags: [library] -brief: Task class and related functions -library-type: library ---- diff --git a/docs/includes/stlab/concurrency/task/operator!=.md b/docs/includes/stlab/concurrency/task/operator!=.md deleted file mode 100644 index ac1ae7756..000000000 --- a/docs/includes/stlab/concurrency/task/operator!=.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: function -title: stlab::operator!= -tags: [library] -scope: stlab -pure-name: operator!= -brief: Compares a task for not equal an empty task -description: Compares a task for not equal an empty task -defined-in-header: stlab/concurrency/task.hpp -entities: - - kind: overloads - list: - - name: operator!= - pure-name: operator!= - declaration: | - bool operator!=(const task& x, std::nullptr_t) - description: Checks if the given task `x` is not equal an empty task - - name: operator!= - pure-name: when_all - declaration: | - bool operator!=(std::nullptr_t, const task& x) - description: Checks if the given task `x` is not equal an empty task - - kind: parameters - list: - - name: x - description: The task that shall be compared against an empty task - - kind: result - description: Returns true, if the given task is not equal an empty task. ---- diff --git a/docs/includes/stlab/concurrency/task/operator().md b/docs/includes/stlab/concurrency/task/operator().md deleted file mode 100644 index c5d5d7d24..000000000 --- a/docs/includes/stlab/concurrency/task/operator().md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: method -title: stlab::task::operator() -tags: [library] -scope: task -pure-name: operator() -defined-in-header: stlab/concurrency/task.hpp -brief: Invoke the task -entities: - - kind: methods - list: - - name: stlab::task::operator() - pure-name: operator() - defined-in-header: stlab/concurrency/task.hpp - declaration: | - void operator()(Args... args) noexcept - description: Invokes the task - - kind: parameters - list: - - name: args - description: The arguments for calling the stored function. - ---- diff --git a/docs/includes/stlab/concurrency/task/operator==.md b/docs/includes/stlab/concurrency/task/operator==.md deleted file mode 100644 index 24907c49e..000000000 --- a/docs/includes/stlab/concurrency/task/operator==.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -layout: function -title: stlab::operator== -tags: [library] -scope: stlab -pure-name: operator== -brief: Checks if a given task is equal to an empty task -description: Checks if a given task is equal to an empty task -annotation: template function -defined-in-header: stlab/concurrency/task.hpp -entities: - - kind: overloads - list: - - name: operator== - pure-name: operator== - declaration: | - bool operator==(const task& x, std::nullptr_t) - description: Checks if the given task `x` is equal to an empty task - - name: operator== - pure-name: when_all - declaration: | - bool operator==(std::nullptr_t, const task& x) - description: Checks if the given task `x` is equal to an empty task - - kind: parameters - list: - - name: x - description: The task that shall be compared against an empty task - - kind: result - description: Returns true, if the given task is equal to an empty task. ---- diff --git a/docs/includes/stlab/concurrency/task/swap.md b/docs/includes/stlab/concurrency/task/swap.md deleted file mode 100644 index 7642e22de..000000000 --- a/docs/includes/stlab/concurrency/task/swap.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -layout: function -title: stlab::swap -tags: [library] -scope: stlab -pure-name: swap -brief: Exchanges two tasks -description: Exchanges two task -defined-in-header: stlab/concurrency/task.hpp -entities: - - kind: overloads - list: - - name: swap - pure-name: swap - declaration: | - void swap(task& x, task& y) - description: Swaps task x and task y - - kind: parameters - list: - - name: x - description: The one task that shall be exchanged - - name: y - description: The other task that shall be exchanged ---- diff --git a/docs/includes/stlab/concurrency/task/task/index.md b/docs/includes/stlab/concurrency/task/task/index.md deleted file mode 100644 index 794dec2dd..000000000 --- a/docs/includes/stlab/concurrency/task/task/index.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: class -title: stlab::task -tags: [library] -scope: stlab -pure-name: task -defined-in-header: stlab/concurrency/task.hpp -dtor: default -annotation: template class -declaration: - - | - template - class task; /* undefined */ - - | - template - class task -brief: | - Class template `stlab::task` is a general-purpose polymorphic function wrapper. Instances of `stlab::task` can store, move, and invoke any [Callable](http://en.cppreference.com/w/cpp/named_req/Callable) target -- functions, lambda expressions, bind expressions, or other function objects, as well as pointers to member functions and pointers to data members. -description: | - The stored callable object is called the target of `stlab::task`. If an `stlab::task` contains no target, it is called _empty_. Invoking the target of an empty `stlab::task` results in [`std::bad_function_call`](http://en.cppreference.com/w/cpp/utility/functional/bad_function_call) exception being thrown. - - `stlab::task` is Similar to [`std::function`](http://en.cppreference.com/w/cpp/utility/functional/function) except it is not copyable and supports move-only and mutable callable targets which is especially useful for targets that may only be invoked once, often useful to deliver a message or payload in tasking or messaging system. - - `stlab::task` satisfies the requirements of [MoveConstructible](http://en.cppreference.com/w/cpp/named_req/MoveConstructible) and [MoveAssignable](http://en.cppreference.com/w/cpp/named_req/MoveAssignable). - -member-types: - - type: result_type - definition: R ---- diff --git a/docs/includes/stlab/concurrency/task/task/operator=.md b/docs/includes/stlab/concurrency/task/task/operator=.md deleted file mode 100644 index 9d5cf0fe1..000000000 --- a/docs/includes/stlab/concurrency/task/task/operator=.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -layout: method -title: stlab::task::operator= -tags: [library] -scope: task -pure-name: operator= -defined-in-header: stlab/concurrency/task.hpp -brief: Move assignment operator -entities: - - kind: methods - list: - - name: stlab::task::operator= - pure-name: operator= - defined-in-header: stlab/concurrency/task.hpp - declaration: | - task& operator=(task&& x) noexcept - description: Moves the given task `x` into `this`. - - name: stlab::task::operator= - pure-name: operator= - defined-in-header: stlab/concurrency/task.hpp - declaration: | - task& operator=(std::nullptr_t) noexcept - description: Destroys the current function and creates a new empty one. - - kind: parameters - list: - - name: x - description: The task that shall be moved into this. - - kind: result - description: | - `*this` ---- diff --git a/docs/includes/stlab/concurrency/task/task/operator_bool.md b/docs/includes/stlab/concurrency/task/task/operator_bool.md deleted file mode 100644 index 4ef24e544..000000000 --- a/docs/includes/stlab/concurrency/task/task/operator_bool.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: method -title: stlab::task::operator bool -tags: [library] -scope: task -pure-name: operator bool -defined-in-header: stlab/concurrency/task.hpp -brief: Check if the task can be invoked -entities: - - kind: methods - list: - - name: stlab::task::operator bool - pure-name: operator bool - defined-in-header: stlab/concurrency/task.hpp - declaration: | - explicit operator bool() const - description: Used to determine if the task can be invoked - - kind: result - description: | - `true` iff the task can be invoked. ---- diff --git a/docs/includes/stlab/concurrency/task/task/swap.md b/docs/includes/stlab/concurrency/task/task/swap.md deleted file mode 100644 index a48d63676..000000000 --- a/docs/includes/stlab/concurrency/task/task/swap.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: method -title: stlab::task::swap -tags: [library] -scope: task -pure-name: swap -defined-in-header: stlab/concurrency/task.hpp -brief: Swaps an other task with this -entities: - - kind: methods - list: - - name: stlab::task::swap - pure-name: swap - defined-in-header: stlab/concurrency/task.hpp - declaration: | - void swap(task& x) - description: Exchanges this task with the passed one. - - kind: parameters - list: - - name: x - description: The task that shall be exchanged with this ---- diff --git a/docs/includes/stlab/concurrency/task/task/target.md b/docs/includes/stlab/concurrency/task/task/target.md deleted file mode 100644 index 24e30f61a..000000000 --- a/docs/includes/stlab/concurrency/task/task/target.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -layout: method -title: stlab::task::target -tags: [library] -scope: task -pure-name: target -defined-in-header: stlab/concurrency/task.hpp -brief: Get the underlying function -entities: - - kind: methods - list: - - name: stlab::task::target - pure-name: target - defined-in-header: stlab/concurrency/task.hpp - declaration: | - template - T* target() - description: Nonconst variant - - name: stlab::task::target - pure-name: target - defined-in-header: stlab/concurrency/task.hpp - declaration: | - template - const T* target() const - description: Const variant - - kind: result - description: | - A pointer to the underlying function, if `target_type() == typeid(T)`. Otherwise, `nullptr`. ---- diff --git a/docs/includes/stlab/concurrency/task/task/target_type.md b/docs/includes/stlab/concurrency/task/task/target_type.md deleted file mode 100644 index 6a75fa762..000000000 --- a/docs/includes/stlab/concurrency/task/task/target_type.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -layout: method -title: stlab::task::target_type -tags: [library] -scope: task -pure-name: target_type -defined-in-header: stlab/concurrency/task.hpp -brief: Get type information about the underlying function -entities: - - kind: methods - list: - - name: stlab::task::target_type - pure-name: target_type - defined-in-header: stlab/concurrency/task.hpp - declaration: | - const std::type_info& target_type() const - description: Gives type information about the underlying function - - kind: result - description: | - Type information about the underlying function ---- diff --git a/docs/includes/stlab/concurrency/task/task/task.md b/docs/includes/stlab/concurrency/task/task/task.md deleted file mode 100644 index cbb975689..000000000 --- a/docs/includes/stlab/concurrency/task/task/task.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -layout: method -title: stlab::task::task -tags: [library] -scope: task -pure-name: task -defined-in-header: stlab/concurrency/task.hpp -brief: Constructs an `stlab::task` from a variety of sources. -description: | - When the target is a function pointer or std::reference_wrapper, small object optimization is - guaranteed, that is, these targets are always directly stored inside the `stlab::task` object, - no dynamic allocation takes place. Other large objects may be constructed in dynamic allocated - storage and accessed by the `stlab::task` object through a pointer. -entities: - - kind: methods - list: - - name: stlab::task::task - pure-name: task - defined-in-header: stlab/concurrency/task.hpp - declaration: | - constexpr task() noexcept; - description: Creates an _empty_ task. - - name: stlab::task::task - pure-name: task - defined-in-header: stlab/concurrency/task.hpp - declaration: | - constexpr task(std::nullptr_t) noexcept; - description: Creates an _empty_ task. - - name: stlab::task::task - pure-name: task - defined-in-header: stlab/concurrency/task.hpp - declaration: | - task(const task&) = delete; - description: Copying of a task is disabled - - name: stlab::task::task - pure-name: task - defined-in-header: stlab/concurrency/task.hpp - declaration: | - task(task&& other) noexcept; - description: > - Moves the _target_ of `other` to the target of `*this`. If `other` is _empty_, `*this` - will be _empty_ after the call too. `other` is in a partially formed state after the - call. - - name: stlab::task::task - pure-name: task - defined-in-header: stlab/concurrency/task.hpp - declaration: | - template - task(F&& f); - description: > - Initializes the _target_ with a copy of `f`. If `f` is a null pointer to function, null - pointer to member, or _empty_ `std::function`, then `*this` will be _empty_ - after the call. [_To be added for C++17._ This constructor does not participate in - overload resolution unless `f` is - [Callable](http://en.cppreference.com/w/cpp/named_req/Callable) for argument types - `Args...` and return type `R`.] - - kind: parameters - list: - - name: other - description: > - a task object used to initialize `*this`. - - name: f - description: > - a callable used to initialize `*this`. ----