mirror of
https://github.com/boostorg/cobalt.git
synced 2026-01-19 04:02:16 +00:00
doc typo fixes
This commit is contained in:
@@ -1,6 +1,6 @@
|
|||||||
= Motivation
|
= Motivation
|
||||||
|
|
||||||
Many languages programming languages
|
Many programming languages
|
||||||
like node.js and python provide easy to use single-threaded concurrency frameworks.
|
like node.js and python provide easy to use single-threaded concurrency frameworks.
|
||||||
While more complex than synchronous code,
|
While more complex than synchronous code,
|
||||||
single threaded asynchronicity avoids many of the pitfalls & overhead of multi-threading.
|
single threaded asynchronicity avoids many of the pitfalls & overhead of multi-threading.
|
||||||
@@ -11,9 +11,9 @@ This allows to write applications that *do multiple things simultaneously* on a
|
|||||||
This library is meant to provide this to C++: *simple single threaded asynchronicity*
|
This library is meant to provide this to C++: *simple single threaded asynchronicity*
|
||||||
akin to node.js and asyncio in python that works with existing libraries like
|
akin to node.js and asyncio in python that works with existing libraries like
|
||||||
`boost.beast`, `boost.mysql` or `boost.redis`.
|
`boost.beast`, `boost.mysql` or `boost.redis`.
|
||||||
It based on `boost.asio`.
|
It is based on `boost.asio`.
|
||||||
|
|
||||||
It takes a collection of concepts from other languages and provides them based on C++20 coroutines.
|
It takes a collection of concepts from other languages and provides them based on C++20 coroutines.
|
||||||
|
|
||||||
- easy asynchronous base functions, such as an async <<main, main>> & <<thread, threads>>
|
- easy asynchronous base functions, such as an async <<main, main>> & <<thread, threads>>
|
||||||
- <<promise, promise>> & <<generator, generator>> types
|
- <<promise, promise>> & <<generator, generator>> types
|
||||||
|
|||||||
@@ -5,7 +5,7 @@ The `gather` function can be used to `co_await` multiple <<awaitable, awaitables
|
|||||||
at once with cancellations being passed through.
|
at once with cancellations being passed through.
|
||||||
|
|
||||||
The function will gather all completion and return them as `system::result`,
|
The function will gather all completion and return them as `system::result`,
|
||||||
i.e. capture conceptions as values. One awaitable throwing an exception will not cancel the others.
|
i.e. capture exceptions as values. One awaitable throwing an exception will not cancel the others.
|
||||||
|
|
||||||
It can be called as a variadic function with multiple <<awaitable>> or as on a range of <<awaitable, awaitables>>.
|
It can be called as a variadic function with multiple <<awaitable>> or as on a range of <<awaitable, awaitables>>.
|
||||||
|
|
||||||
|
|||||||
@@ -174,7 +174,7 @@ cobalt::generator<int> my_gen(std::allocator_arg_t, pmr::polymorphic_allocator<v
|
|||||||
----
|
----
|
||||||
include::../../include/boost/cobalt/generator.hpp[tag=outline]
|
include::../../include/boost/cobalt/generator.hpp[tag=outline]
|
||||||
----
|
----
|
||||||
<1> This allows code like `while (gen) co_await gen:`
|
<1> This allows code like `while (gen) co_await gen;`
|
||||||
<2> Supports <<interrupt_await>>
|
<2> Supports <<interrupt_await>>
|
||||||
<3> A cancelled generator maybe be resumable
|
<3> A cancelled generator maybe be resumable
|
||||||
|
|
||||||
|
|||||||
@@ -60,5 +60,5 @@ template<asio::cancellation_type Ct = asio::cancellation_type::all, range<awaita
|
|||||||
__awaitable__ join(PromiseRange && p);
|
__awaitable__ join(PromiseRange && p);
|
||||||
----
|
----
|
||||||
|
|
||||||
NOTE: Selecting an on empty range will cause an exception.
|
NOTE: Selecting an empty range will cause an exception.
|
||||||
|
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
[#main]
|
[#main]
|
||||||
== cobalt/main.hpp
|
== cobalt/main.hpp
|
||||||
|
|
||||||
The easiest way to get started with an cobalt application is to use the `co_main` function with the following signature:
|
The easiest way to get started with a cobalt application is to use the `co_main` function with the following signature:
|
||||||
|
|
||||||
[source,cpp]
|
[source,cpp]
|
||||||
----
|
----
|
||||||
@@ -23,13 +23,13 @@ cobalt::main co_main(int argc, char *argv[])
|
|||||||
----
|
----
|
||||||
<1> get the executor `main` running on
|
<1> get the executor `main` running on
|
||||||
<2> Use it with an asio object
|
<2> Use it with an asio object
|
||||||
<3> `co_await` an cobalt operation
|
<3> `co_await` a cobalt operation
|
||||||
|
|
||||||
The main promise will create an `asio::signal_set` and uses it for cancellation.
|
The main promise will create an `asio::signal_set` and uses it for cancellation.
|
||||||
`SIGINT` becomes total , while `SIGTERM` becomes terminal cancellation.
|
`SIGINT` becomes total , while `SIGTERM` becomes terminal cancellation.
|
||||||
|
|
||||||
NOTE: The cancellation will not be forwarded to detached coroutines.
|
NOTE: The cancellation will not be forwarded to detached coroutines.
|
||||||
The user will need to take care to end then on cancellation,
|
The user will need to take care to end them on cancellation,
|
||||||
since the program otherwise doesn't allow graceful termination.
|
since the program otherwise doesn't allow graceful termination.
|
||||||
|
|
||||||
=== Executor
|
=== Executor
|
||||||
@@ -42,7 +42,7 @@ It will be assigned to the `cobalt::this_thread::get_executor()` .
|
|||||||
[#main-allocator]
|
[#main-allocator]
|
||||||
|
|
||||||
It also creates a memory resource that will be used as a default for internal memory allocations.
|
It also creates a memory resource that will be used as a default for internal memory allocations.
|
||||||
It will be assigned to the `thread_local` to the `cobalt::this_thread::get_default_resource()`.
|
It will be assigned to `cobalt::this_thread::get_default_resource()`.
|
||||||
|
|
||||||
[#main-promise]
|
[#main-promise]
|
||||||
=== Promise
|
=== Promise
|
||||||
|
|||||||
@@ -6,7 +6,7 @@ An operation in `cobalt` is an <<awaitable, awaitable>> wrapping an `asio` opera
|
|||||||
[#use_op]
|
[#use_op]
|
||||||
=== use_op
|
=== use_op
|
||||||
|
|
||||||
The `use_op` token is the direct to create an op,
|
The `use_op` token is the direct way to create an op,
|
||||||
i.e. using `cobalt::use_op` as the completion token will create the required awaitable.
|
i.e. using `cobalt::use_op` as the completion token will create the required awaitable.
|
||||||
|
|
||||||
[source,cpp]
|
[source,cpp]
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ cobalt::promise<void> do_wait()
|
|||||||
<1> Wait for a variadic set of <<awaitable, awaitables>>
|
<1> Wait for a variadic set of <<awaitable, awaitables>>
|
||||||
<2> wait for a vector of <<awaitable, awaitables>>
|
<2> wait for a vector of <<awaitable, awaitables>>
|
||||||
|
|
||||||
The first parameter so `race` can be a https://en.cppreference.com/w/cpp/named_req/UniformRandomBitGenerator::[uniform random bit generator].
|
The first parameter so `race` can be a https://en.cppreference.com/w/cpp/named_req/UniformRandomBitGenerator[uniform random bit generator].
|
||||||
|
|
||||||
|
|
||||||
.Signatures of race
|
.Signatures of race
|
||||||
|
|||||||
@@ -31,7 +31,7 @@ Otherwise, it'll default to the thread_local executor.
|
|||||||
[#task-allocator]
|
[#task-allocator]
|
||||||
|
|
||||||
The memory resource is *NOT* taken from the `thread_local` <<this_thread, get_default_resource>> function,
|
The memory resource is *NOT* taken from the `thread_local` <<this_thread, get_default_resource>> function,
|
||||||
but `pmr::get_default_resource(),
|
but `pmr::get_default_resource()`,
|
||||||
unless a `std::allocator_arg` is used in any position followed by a `polymorphic_allocator` argument.
|
unless a `std::allocator_arg` is used in any position followed by a `polymorphic_allocator` argument.
|
||||||
|
|
||||||
[source, cpp]
|
[source, cpp]
|
||||||
|
|||||||
@@ -15,7 +15,7 @@ cobalt::thread my_thread()
|
|||||||
----
|
----
|
||||||
<1> get the executor `thread` running on
|
<1> get the executor `thread` running on
|
||||||
<2> Use it with an asio object
|
<2> Use it with an asio object
|
||||||
<3> `co_await` an cobalt operation
|
<3> `co_await` a cobalt operation
|
||||||
|
|
||||||
To use a thread you can use it like a `std::thread`:
|
To use a thread you can use it like a `std::thread`:
|
||||||
|
|
||||||
@@ -58,7 +58,7 @@ It will be assigned to the `cobalt::this_thread::get_executor()` .
|
|||||||
[#thread-allocator]
|
[#thread-allocator]
|
||||||
|
|
||||||
It also creates a memory resource that will be used as a default for internal memory allocations.
|
It also creates a memory resource that will be used as a default for internal memory allocations.
|
||||||
It will be assigned to the `thread_local` to the `cobalt::this_thread::get_default_resource()`.
|
It will be assigned to `cobalt::this_thread::get_default_resource()`.
|
||||||
|
|
||||||
[#thread-outline]
|
[#thread-outline]
|
||||||
=== Outline
|
=== Outline
|
||||||
|
|||||||
@@ -24,7 +24,7 @@ that returns an <<awaitable, awaitable>> or by providing the teardown as the thi
|
|||||||
|
|
||||||
[source,cpp]
|
[source,cpp]
|
||||||
----
|
----
|
||||||
using ws_stream = beast::websocket::stream<asio::ip::tcp::socket>>;
|
using ws_stream = beast::websocket::stream<asio::ip::tcp::socket>;
|
||||||
cobalt::promise<ws_stream> connect(urls::url); // <1>
|
cobalt::promise<ws_stream> connect(urls::url); // <1>
|
||||||
cobalt::promise<void> disconnect(ws_stream &ws); // <2>
|
cobalt::promise<void> disconnect(ws_stream &ws); // <2>
|
||||||
|
|
||||||
|
|||||||
@@ -1,4 +1,4 @@
|
|||||||
== Entry into an cobalt environment
|
== Entry into a cobalt environment
|
||||||
|
|
||||||
In order to use <<awaitable, awaitables>> we need to be able to `co_await` them, i.e. be within a coroutine.
|
In order to use <<awaitable, awaitables>> we need to be able to `co_await` them, i.e. be within a coroutine.
|
||||||
|
|
||||||
@@ -24,7 +24,7 @@ cobalt::thread my_thread()
|
|||||||
co_return;
|
co_return;
|
||||||
}
|
}
|
||||||
|
|
||||||
int main(int argc, char ** argv[])
|
int main(int argc, char * argv[])
|
||||||
{
|
{
|
||||||
auto t = my_thread();
|
auto t = my_thread();
|
||||||
t.join();
|
t.join();
|
||||||
@@ -41,7 +41,7 @@ cobalt::task<void> my_thread()
|
|||||||
co_return;
|
co_return;
|
||||||
}
|
}
|
||||||
|
|
||||||
int main(int argc, char ** argv[])
|
int main(int argc, char * argv[])
|
||||||
{
|
{
|
||||||
cobalt::run(my_task()); // sync
|
cobalt::run(my_task()); // sync
|
||||||
asio::io_context ctx;
|
asio::io_context ctx;
|
||||||
|
|||||||
@@ -79,5 +79,5 @@ include::../../example/echo_server.cpp[tag=main]
|
|||||||
|
|
||||||
The <<with, with>> function shown above, will run a function with a resource such as <<wait_group, wait_group>>.
|
The <<with, with>> function shown above, will run a function with a resource such as <<wait_group, wait_group>>.
|
||||||
On scope exit `with` will invoke & `co_await` an asynchronous teardown function.
|
On scope exit `with` will invoke & `co_await` an asynchronous teardown function.
|
||||||
This will cause all connections to be properly shutdown before `co_main` exists.
|
This will cause all connections to be properly shutdown before `co_main` exits.
|
||||||
|
|
||||||
|
|||||||
@@ -2,7 +2,7 @@
|
|||||||
|
|
||||||
This library provides a set of easy to use coroutine primitives & utilities running on top of boost.asio.
|
This library provides a set of easy to use coroutine primitives & utilities running on top of boost.asio.
|
||||||
These will be of interest for applications that perform a lot of IO that want to not block unnecessarily,
|
These will be of interest for applications that perform a lot of IO that want to not block unnecessarily,
|
||||||
yet still want to have linear & readable code (i..e. avoid callbacks).
|
yet still want to have linear & readable code (i.e. avoid callbacks).
|
||||||
|
|
||||||
A minimum of Boost 1.82 is necessary as the ASIO in that version has needed support. C++ 20 is needed for C++ coroutines.
|
A minimum of Boost 1.82 is necessary as the ASIO in that version has needed support. C++ 20 is needed for C++ coroutines.
|
||||||
|
|
||||||
@@ -244,7 +244,7 @@ cobalt::promise<void> delay(int ms)
|
|||||||
cobalt::main co_main(int argc, char ** argv)
|
cobalt::main co_main(int argc, char ** argv)
|
||||||
{
|
{
|
||||||
auto res = co_await race(delay(100), delay(50));
|
auto res = co_await race(delay(100), delay(50));
|
||||||
asert(res == 1); // delay(50) completes earlier, delay(100) is not cancelled
|
assert(res == 1); // delay(50) completes earlier, delay(100) is not cancelled
|
||||||
co_return 0u;
|
co_return 0u;
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user