Skip to content

Commit

Permalink
Refactor ascidoc adoc files to Antora. core features and advenced fea…
Browse files Browse the repository at this point in the history 
…tures are now split in multiple adoc files.
  • Loading branch information
@pderop
pderop committed May 2, 2024
1 parent a482fbb commit 2d340c0
Show file tree
Hide file tree
Showing 43 changed files with 2,718 additions and 2,842 deletions.
134 changes: 28 additions & 106 deletions docs/modules/ROOT/nav.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,107 +1,29 @@
= Reactor 3 Reference Guide
Stephane Maldini <https://twitter.com/smaldini[@smaldini]>; Simon Baslé <https://twitter.com/simonbasle[@simonbasle]>
ifndef::host-github[:ext-relative: {outfilesuffix}]
:doctype: book
:icons: font
:toc2:
:sectnums:
:sectanchors:
* xref:aboutDoc.adoc[]
* xref:gettingStarted.adoc[]
* xref:reactiveProgramming.adoc[]
* xref:coreFeatures.adoc[]
** xref:coreFeatures/flux.adoc[]
** xref:coreFeatures/mono.adoc[]
** xref:coreFeatures/simple-ways-to-create-a-flux-or-mono-and-subscribe-to-it.adoc[]
** xref:coreFeatures/programmatically-creating-sequence.adoc[]
** xref:coreFeatures/schedulers.adoc[]
** xref:coreFeatures/error-handling.adoc[]
** xref:coreFeatures/sinks.adoc[]
* xref:kotlin.adoc[]
* xref:testing.adoc[]
* xref:debugging.adoc[]
* xref:metrics.adoc[]
* xref:advancedFeatures.adoc[]
** xref:advancedFeatures/advanced-mutualizing-operator-usage.adoc[]
** xref:advancedFeatures/reactor-hotCold.adoc[]
** xref:advancedFeatures/advanced-broadcast-multiple-subscribers-connectableflux.adoc[]
** xref:advancedFeatures/advanced-three-sorts-batching.adoc[]
** xref:advancedFeatures/advanced-parallelizing-parralelflux.adoc[]
** xref:advancedFeatures/scheduler-factory.adoc[]
** xref:advancedFeatures/hooks.adoc[]
** xref:advancedFeatures/context.adoc[]
** xref:advanced-contextPropagation.adoc[]
** xref:advancedFeatures/cleanup.adoc[]
** xref:advancedFeatures/null-safety.adoc[]
* xref:appendices.adoc[]
include::aboutDoc.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/aboutDoc.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<about-doc>>"
endif::[]

include::gettingStarted.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/gettingStarted.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<getting-started>>"
endif::[]

include::reactiveProgramming.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/reactiveProgramming.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<intro-reactive>>"
endif::[]

include::coreFeatures.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/coreFeatures.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<core-features>>"
endif::[]

//TODO see other sections from consuming.adoc

include::kotlin.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/kotlin.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<kotlin>>"
endif::[]

include::testing.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/testing.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<testing>>"
endif::[]

include::debugging.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/debugging.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<debugging>>"
endif::[]

include::metrics.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/metrics.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<metrics>>"
endif::[]
include::metrics-details.adoc[]

include::advancedFeatures.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/advancedFeatures.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<advanced>>"
endif::[]


[appendix]
include::apdx-operatorChoice.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/apdx-operatorChoice.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<which-operator>>"
endif::[]

[appendix]
include::apdx-howtoReadMarbles.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/apdx-howtoReadMarbles.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<howtoReadMarbles>>"
endif::[]

[appendix]
include::faq.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/faq.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<faq>>"
endif::[]

[appendix]
include::apdx-reactorExtra.adoc[leveloffset=1]
ifeval::["{backend}" == "html5"]
https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/apdx-reactorExtra.adoc[Suggest Edit^, title="Suggest an edit to the above section via github", role="fa fa-edit"]
to "<<reactor-extra>>"
endif::[]

//TODO later add appendices about internals, writing operators, fusion
//[appendix]
//include::apdx-implem.adoc[]
//
//[appendix]
//include::apdx-writingOperator.adoc[]
//[appendix]
//include::apdx-optimizations.adoc[]

//TODO later add appendix about migrating from RxJava?
//[appendix]
//include::apdx-migrating.adoc[]
41 changes: 24 additions & 17 deletions docs/modules/ROOT/pages/aboutDoc.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,14 @@
[[about-doc]]
= About the Documentation
:linkattrs:

Stephane Maldini <https://twitter.com/smaldini[@smaldini]>; Simon Baslé <https://twitter.com/simonbasle[@simonbasle]> Version {project-version}

This section provides a brief overview of Reactor reference documentation. You do not
need to read this guide in a linear fashion. Each piece stands on its own, though they
often refer to other pieces.

[[latest-version-copyright-notice]]
== Latest Version & Copyright Notice
The Reactor reference guide is available as HTML documents. The latest copy is available
at https://projectreactor.io/docs/core/release/reference/index.html
Expand All @@ -13,10 +17,11 @@ Copies of this document may be made for your own use and for distribution to oth
provided that you do not charge any fee for such copies and further provided that each
copy contains this Copyright Notice, whether distributed in print or electronically.

[[contributing-to-the-documentation]]
== Contributing to the Documentation
The reference guide is written in
https://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoc], and you can find its sources at
https://github.com/reactor/reactor-core/tree/main/docs/asciidoc.
https://asciidoctor.org/docs/asciidoc-writers-guide/[Asciidoc] using https://docs.antora.org/antora/latest/[Antora], and you can find its
sources at {reactor-github-repo}/docs/.

If you have an improvement or a suggestion, we will be happy to get a pull request from you!

Expand All @@ -26,12 +31,13 @@ rendering. Some of the sections rely on included files, so GitHub rendering is
not always complete.

ifeval::["{backend}" == "html5"]
TIP: To facilitate documentation edits, most sections have a link at the end that opens
an edit UI directly on GitHub for the main source file for that section. These links are
only present in the HTML5 version of this reference guide. They look like the following:
link:https://github.com/reactor/reactor-core/edit/main/docs/asciidoc/aboutDoc.adoc[Suggest Edit^, role="fa fa-edit"] to <<about-doc>>.
TIP: To facilitate documentation edits, you can edit the current page from the `Edit this Page` link located in the upper right corner sidebar. The link opens
an edit `UI` directly on `GitHub` for the main source file for the current page. These links are
only present in the `HTML5` version of this reference guide. They look like the following link:
link:https://github.com/reactor/reactor-core/edit/main/docs/modules/ROOT/pages/aboutDoc.adoc[Edit this Page^, role="fa fa-edit"] to xref:aboutDoc.adoc[About the Documentation].
endif::[]

[[getting-help]]
== Getting Help
You can reach out for help in several ways with Reactor:

Expand All @@ -44,22 +50,23 @@ essential features) and https://github.com/reactor/reactor-addons/issues[reactor
(which covers reactor-test and adapters issues).

NOTE: All of Reactor is open source,
https://github.com/reactor/reactor-core/tree/main/docs/asciidoc[including this
{reactor-github-repo}/docs[including this
documentation]. If you find problems with the docs or if you want to improve them,
please https://github.com/reactor/.github/blob/main/CONTRIBUTING.md[get involved].

[[where-to-go-from-here]]
== Where to Go from Here
* Head to <<getting-started>> if you feel like jumping straight into the code.
* Head to xref:gettingStarted.adoc[Getting Started] if you feel like jumping straight into the code.
* If you are new to reactive programming, though, you should probably start with the
<<intro-reactive>>.
xref:reactiveProgramming.adoc[Introduction to Reactive Programming].
* If you are familiar with Reactor concepts and are just looking for the right tool
for the job but cannot think of a relevant operator, try the <<which-operator>> Appendix.
* In order to dig deeper into the core features of Reactor, head to <<core-features>> to
for the job but cannot think of a relevant operator, try the xref:apdx-operatorChoice.adoc[Which operator do I need?] Appendix.
* In order to dig deeper into the core features of Reactor, head to xref:coreFeatures.adoc[Reactor Core Features] to
learn:
** More about Reactor's reactive types in the <<flux>> and <<mono>>
** More about Reactor's reactive types in the xref:coreFeatures/flux.adoc[`Flux`, an Asynchronous Sequence of 0-N Items] and xref:coreFeatures/mono.adoc[`Mono`, an Asynchronous 0-1 Result]
sections.
** How to switch threading contexts using <<schedulers,a scheduler>>.
** How to handle errors in the <<error.handling>> section.
* Unit testing? Yes it is possible with the `reactor-test` project! See <<testing>>.
* <<producing>> offers a more advanced way of creating reactive sources.
* Other advanced topics are covered in <<advanced>>.
** How to switch threading contexts using xref:apdx-reactorExtra.adoc#extra-schedulers[a scheduler].
** How to handle errors in the xref:coreFeatures/error-handling.adoc[Handling Errors] section.
* Unit testing? Yes it is possible with the `reactor-test` project! See xref:testing.adoc[Testing].
* xref:producing.adoc[Programmatically creating a sequence] offers a more advanced way of creating reactive sources.
* Other advanced topics are covered in xref:advancedFeatures.adoc[Advanced Features and Concepts].
20 changes: 11 additions & 9 deletions docs/modules/ROOT/pages/advanced-contextPropagation.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@ Reactor-Core supports two modes of operation with `io.micrometer:context-propaga
Please note that this mode applies only to new subscriptions, so it is recommended to
enable this hook when the application starts.

Their key differences are discussed in the context of either <<context-writing, writing
data>> to Reactor `Context`, or <<context-accessing,accessing `ThreadLocal` state>> that
Their key differences are discussed in the context of either xref:advanced-contextPropagation.adoc#context-writing[writing data]
to Reactor `Context`, or xref:advanced-contextPropagation.adoc#context-accessing[accessing `ThreadLocal` state] that
reflects the contents of the `Context` of currently attached `Subscriber` for reading.

[[context-writing]]
Expand All @@ -28,13 +28,14 @@ Depending on the individual application, you might either have to store already
`ThreadLocal` state as entries in the `Context`, or might only need to directly populate
the `Context`.

[[contextwrite-operator]]
=== `contextWrite` Operator

When the values meant to be accessed as `ThreadLocal` are not (or do not need to be)
present at the time of subscription, they can immediately be stored in the `Context`:

====
[source,java]
[%unbreakable]
----
// assuming TL is known to Context-Propagation as key TLKEY.
static final ThreadLocal<String> TL = new ThreadLocal<>();
Expand All @@ -49,8 +50,8 @@ Mono.deferContextual(ctx ->
.block(); // returns "delayed ctx[TLKEY]=HELLO, TL=null" in default mode
// returns "delayed ctx[TLKEY]=HELLO, TL=HELLO" in automatic mode
----
====

[[contextcapture-operator]]
=== `contextCapture` Operator
This operator can be used when one needs to capture `ThreadLocal` value(s) at subscription time and reflect these values in the Reactor `Context` for the benefit of upstream operators.

Expand All @@ -61,8 +62,8 @@ to populate the Reactor `Context`.
As a result, if there were any `ThreadLocal` values during subscription phase, for which there is a registered `ThreadLocalAccessor`, their values would now be stored in the Reactor `Context` and visible
at runtime in upstream operators.

====
[source,java]
[%unbreakable]
----
// assuming TL is known to Context-Propagation as key TLKEY.
static final ThreadLocal<String> TL = new ThreadLocal<>();
Expand All @@ -78,7 +79,6 @@ Mono.deferContextual(ctx ->
.block(); // returns "delayed ctx[TLKEY]=HELLO, TL=null" in default mode
// returns "delayed ctx[TLKEY]=HELLO, TL=HELLO" in automatic mode
----
====

NOTE: In the **automatic** mode, blocking operators, such as `Flux#blockFirst()`,
`Flux#blockLast()`, `Flux#toIterable()`, `Mono#block()`, `Mono#blockOptional()`, and
Expand All @@ -97,6 +97,7 @@ Reactor-Core performs `ThreadLocal` state restoration using the values
stored in `Context` and `ThreadLocalAccessor` instances registered in `ContextRegistry`
that match by key.

[[default-mode-operators-for-snapshot-restoration:-handle-and-tap]]
=== Default mode operators for snapshot restoration: `handle` and `tap`

In the **default** mode, both `Flux` and `Mono` variants of `handle` and `tap` will have
Expand All @@ -113,8 +114,8 @@ These operators will ensure restoration is performed around the user-provided co
The intent is to have a minimalistic set of operators transparently perform restoration.
As a result we chose operators with rather general and broad applications (one with transformative capabilities, one with side-effect capabilities)

====
[source,java]
[%unbreakable]
----
//assuming TL is known to Context-Propagation.
static final ThreadLocal<String> TL = new ThreadLocal<>();
Expand All @@ -130,8 +131,8 @@ Mono.delay(Duration.ofSeconds(1))
.contextCapture()
.block(); // prints "null" and returns "handled delayed TL=HELLO"
----
====

[[automatic-mode]]
=== Automatic mode

In the **automatic** mode, all operators restore `ThreadLocal` state across `Thread`
Expand All @@ -154,6 +155,7 @@ treat absent keys in the `Context` for registered instances of `ThreadLocalAcces
signals to clear the corresponding `ThreadLocal` state. This is especially important for
an empty `Context`, which clears all state for registered `ThreadLocalAccessor` instances.

[[which-mode-should-i-choose]]
== Which mode should I choose?

Both **default** and **automatic** modes have an impact on performance. Accessing
Expand All @@ -167,4 +169,4 @@ compromise to make. The **automatic** mode, depending on the flow of your applic
the amount of operators used, can be either better or worse than the **default** mode. The
only recommendation that can be given is to measure how your application behaves and what
scalability and performance characteristics you obtain when presented with a load you
expect.
expect.

0 comments on commit 2d340c0

Please sign in to comment.