diff --git a/CMakeLists.txt b/CMakeLists.txt index 776cff46..fa38d1d3 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -100,7 +100,7 @@ else() file(GLOB_RECURSE ADOC_FILES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.adoc) add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html - COMMAND asciidoctor ${CMAKE_CURRENT_SOURCE_DIR}/doc/index.adoc --require asciidoctor-diagram --require asciidoctor-multipage -b multipage_html5 -o ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html + COMMAND asciidoctor ${CMAKE_CURRENT_SOURCE_DIR}/doc/index.adoc --require asciidoctor-diagram --require asciidoctor-multipage -b multipage_html5 -a generate-diagram -o ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html DEPENDS ${ADOC_FILES}) add_custom_target(boost_cobalt_doc DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html) diff --git a/doc/Jamfile b/doc/Jamfile index b6164133..19564375 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -4,7 +4,7 @@ import asciidoctor ; -html index.html : index.adoc : "-r asciidoctor-diagram" ; +html index.html : index.adoc ; install html_ : index.html : html ; diff --git a/doc/background/lazy_eager.adoc b/doc/background/lazy_eager.adoc index 4bb6865e..889d37c9 100644 --- a/doc/background/lazy_eager.adoc +++ b/doc/background/lazy_eager.adoc @@ -37,8 +37,8 @@ Coro Done resumed twice ---- - -[mermaid] +ifdef::generate-diagram[] +[mermaid, target=lazy_eager1] ---- sequenceDiagram participant main; @@ -54,6 +54,11 @@ sequenceDiagram lazy->>main: co_return Note left of main: "resumed twice" ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/lazy_eager1.png[] +endif::[] Whereas an eager coro would look like this: @@ -90,8 +95,8 @@ Coro Done ---- - -[mermaid] +ifdef::generate-diagram[] +[mermaid, target=lazy_eager2] ---- sequenceDiagram participant main; @@ -104,5 +109,9 @@ sequenceDiagram Note right of lazy: "Coro done" lazy->>main: co_return Note left of main: "resumed once" +---- +endif::[] ----- \ No newline at end of file +ifndef::generate-diagram[] +image::{docdir}/images/lazy_eager2.png[] +endif::[] diff --git a/doc/background/stackless.adoc b/doc/background/stackless.adoc index adbbb8b8..e22c44ac 100644 --- a/doc/background/stackless.adoc +++ b/doc/background/stackless.adoc @@ -30,7 +30,8 @@ main() bar() ---- -[mermaid] +ifdef::generate-diagram[] +[mermaid, target=stackless1] ---- sequenceDiagram main->>+foo: call @@ -38,6 +39,11 @@ sequenceDiagram bar->>-foo: return foo->>-main: return ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/stackless1.png[] +endif::[] Coroutines can be implemented a stackful, which means that it allocates a fixes chunk of memory and stacks function frames similar to a thread. C++20 coroutines are stackless, i.e. they only allocate their own frame and use the callers stack on resumption. Using our previous example: @@ -75,7 +81,9 @@ main() f$example() ---- -[mermaid] + +ifdef::generate-diagram[] +[mermaid, target=stackless2] ---- sequenceDiagram participant main @@ -89,5 +97,10 @@ sequenceDiagram main-->>example: resume example->>-main: co_return ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/stackless2.png[] +endif::[] The same applies if a coroutine gets moved accross threads. \ No newline at end of file diff --git a/doc/images/awaitables.png b/doc/images/awaitables.png new file mode 100644 index 00000000..82808865 Binary files /dev/null and b/doc/images/awaitables.png differ diff --git a/doc/images/generators1.png b/doc/images/generators1.png new file mode 100644 index 00000000..ed191ab3 Binary files /dev/null and b/doc/images/generators1.png differ diff --git a/doc/images/generators2.png b/doc/images/generators2.png new file mode 100644 index 00000000..ed191ab3 Binary files /dev/null and b/doc/images/generators2.png differ diff --git a/doc/images/lazy_eager1.png b/doc/images/lazy_eager1.png new file mode 100644 index 00000000..a9971003 Binary files /dev/null and b/doc/images/lazy_eager1.png differ diff --git a/doc/images/lazy_eager2.png b/doc/images/lazy_eager2.png new file mode 100644 index 00000000..bec78798 Binary files /dev/null and b/doc/images/lazy_eager2.png differ diff --git a/doc/images/stackless1.png b/doc/images/stackless1.png new file mode 100644 index 00000000..d5a3d90b Binary files /dev/null and b/doc/images/stackless1.png differ diff --git a/doc/images/stackless2.png b/doc/images/stackless2.png new file mode 100644 index 00000000..fd72b2ac Binary files /dev/null and b/doc/images/stackless2.png differ diff --git a/doc/index.adoc b/doc/index.adoc index 0b12613e..e00a1676 100644 --- a/doc/index.adoc +++ b/doc/index.adoc @@ -11,6 +11,7 @@ Version 0.1, 29.01.2023 :source-language: c++ :example-caption: Example +:imagesdir: {docdir}/images :leveloffset: +1 diff --git a/doc/primer/awaitables.adoc b/doc/primer/awaitables.adoc index a8ea0f7c..e5635aa6 100644 --- a/doc/primer/awaitables.adoc +++ b/doc/primer/awaitables.adoc @@ -19,8 +19,8 @@ NOTE: Type will be implicitly converted into an awaitable if there is an `operat This documentation will use `awaitable` to include these types, and "actual_awaitable" to refer to type conforming to the above prototype. - -[mermaid] +ifdef::generate-diagram[] +[mermaid, target=awaitables] ---- flowchart TD aw{await_ready?} @@ -28,6 +28,11 @@ flowchart TD aw -->|false| as[await_suspend] as -->|Resume| ar ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/awaitables.png[] +endif::[] In a `co_await` expression the waiting coroutine will first invoke `await_ready` to check if the coroutine needs to suspend. diff --git a/doc/reference/generators.adoc b/doc/reference/generators.adoc index 69afb685..88eb7fc7 100644 --- a/doc/reference/generators.adoc +++ b/doc/reference/generators.adoc @@ -33,7 +33,9 @@ Which will generate the following output In coro 3 In main 4 -[mermaid] + +ifdef::generate-diagram[] +[mermaid, target=generators1] ---- sequenceDiagram participant main; @@ -47,6 +49,11 @@ sequenceDiagram example->>main: co_return 3 Note left of main: "In main 4" ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/generators1.png[] +endif::[] Values can be pushed into the generator, when `Push` (the second template parameter) is set to non-void: @@ -117,7 +124,8 @@ Which will generate the following output In coro 3 In main 4 -[mermaid] +ifdef::generate-diagram[] +[mermaid, target=generators2] ---- sequenceDiagram participant main; @@ -131,6 +139,11 @@ sequenceDiagram example->>main: co_return 3 Note left of main: "In main 4" ---- +endif::[] + +ifndef::generate-diagram[] +image::{docdir}/images/generators2.png[] +endif::[] [#generator-executor] === Executor