You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by or...@apache.org on 2024/02/19 15:49:57 UTC
(camel) 04/10: CAMEL-20410: documentation fixes for camel-disruptor
This is an automated email from the ASF dual-hosted git repository.
orpiske pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
commit de0fab2100eb00f5aa655fd3f27e2d37f9134f46
Author: Otavio Rodolfo Piske <an...@gmail.com>
AuthorDate: Mon Feb 19 13:04:54 2024 +0100
CAMEL-20410: documentation fixes for camel-disruptor
- Fixed samples
- Fixed grammar and typos
- Fixed punctuation
- Added and/or fixed links
---
.../src/main/docs/disruptor-component.adoc | 64 +++++++++++-----------
.../src/main/docs/disruptor-vm-component.adoc | 39 ++++++-------
2 files changed, 53 insertions(+), 50 deletions(-)
diff --git a/components/camel-disruptor/src/main/docs/disruptor-component.adoc b/components/camel-disruptor/src/main/docs/disruptor-component.adoc
index 76e6898a0eb..2d80873d689 100644
--- a/components/camel-disruptor/src/main/docs/disruptor-component.adoc
+++ b/components/camel-disruptor/src/main/docs/disruptor-component.adoc
@@ -15,38 +15,39 @@
*{component-header}*
The Disruptor component provides asynchronous
-https://en.wikipedia.org/wiki/Staged_event-driven_architecture[SEDA] behavior much as the
-standard SEDA component, but utilizes a
-https://github.com/LMAX-Exchange/disruptor[Disruptor] instead of a
+https://en.wikipedia.org/wiki/Staged_event-driven_architecture[SEDA] behavior similarly to the
+standard SEDA component.
+However, it uses a https://github.com/LMAX-Exchange/disruptor[Disruptor] instead of a
http://docs.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/BlockingQueue.html[BlockingQueue]
-utilized by the standard xref:seda-component.adoc[SEDA]. Alternatively, a *disruptor-vm:* endpoint is supported by this component.
+used by the standard xref:seda-component.adoc[SEDA].
+Alternatively, this component supports a xref:disruptor-vm-component.adoc[disruptor-vm] endpoint.
The main advantage of choosing to use the Disruptor component over the
SEDA is performance in use cases where there is high
contention between producer(s) and/or multicasted or concurrent
-Consumers. In those cases, significant increases of throughput and
+Consumers. In those cases, significant increases in throughput and
reduction of latency has been observed. Performance in scenarios without
contention is comparable to the SEDA component.
-The Disruptor is implemented with the intention of mimicing the
-behaviour and options of the SEDA component as much as possible.
-The main differences with the them are the following:
+The Disruptor is implemented with the intention of mimicking the
+behavior and options of the SEDA component as much as possible.
+The main differences between them are the following:
* The buffer used is always bounded in size (default 1024 exchanges).
-* As a the buffer is always bouded, the default behaviour for the
+* As the buffer is always bounded, the default behavior for the
Disruptor is to block while the buffer is full instead of throwing an
-exception. This default behaviour may be configured on the component
+exception. This default behavior may be configured on the component
(see options).
-* The Disruptor enpoints don't implement the BrowsableEndpoint
+* The Disruptor endpoints don't implement the `BrowsableEndpoint`
interface. As such, the exchanges currently in the Disruptor can't be
-retrieved, only the amount of exchanges.
+retrieved, only the number of exchanges.
* The Disruptor requires its consumers (multicasted or otherwise) to be
statically configured. Adding or removing consumers on the fly requires
complete flushing of all pending exchanges in the Disruptor.
* As a result of the reconfiguration: Data sent over a Disruptor is
directly processed and 'gone' if there is at least one consumer, late
joiners only get new exchanges published after they've joined.
-* The *pollTimeout* option is not supported by the Disruptor component.
+* The `pollTimeout` option is not supported by the Disruptor component.
* When a producer blocks on a full Disruptor, it does not respond to
thread interrupts.
@@ -66,10 +67,10 @@ for this component:
== URI format
-----------------------------
- disruptor:someName[?options]
+ disruptor:someId[?options]
-----------------------------
-Where **someName** can be any string that uniquely identifies the
+Where _someId_ can be any string that uniquely identifies the
endpoint within the current CamelContext.
== Options
@@ -100,20 +101,20 @@ published. The following strategies can be chosen:
|Name |Description |Advice
|Blocking | Blocking strategy that uses a lock and condition variable for Consumers
-waiting on a barrier. | This strategy can be used when throughput and low-latency are not as
+waiting on a barrier. | This strategy can be used when throughput and low latency are not as
important as CPU resource.
-|Sleeping |Sleeping strategy that initially spins, then uses a Thread.yield(), and
+|Sleeping |Sleeping strategy that initially spins then uses a `Thread.yield()`, and
eventually for the minimum number of nanos the OS and JVM will allow
while the Consumers are waiting on a barrier. |This strategy is a good compromise between performance and CPU resource.
Latency spikes can occur after quiet periods.
|BusySpin |Busy Spin strategy that uses a busy spin loop for Consumers waiting on a
-barrier. |This strategy will use CPU resource to avoid syscalls which can
+barrier. |This strategy will use CPU resource to avoid _syscalls_ which can
introduce latency jitter. It is best used when threads can be bound to
specific CPU cores.
-|Yielding |Yielding strategy that uses a Thread.yield() for Consumers waiting on a
+|Yielding |Yielding strategy that uses a `Thread.yield()` for Consumers waiting on a
barrier after an initially spinning. |This strategy is a good compromise between performance and CPU resource
without incurring significant latency spikes.
|=======================================================================
@@ -147,10 +148,10 @@ thread pools you can use:
from("disruptor:stageName?concurrentConsumers=5").process(...)
--------------------------------------------------------------
-As for the difference between the two, note a thread pool can
-increase/shrink dynamically at runtime depending on load, whereas the
+As for the difference between the two, note that a thread pool can
+increase/shrink dynamically at runtime depending on load. Whereas the
number of concurrent consumers is always fixed and supported by the
-Disruptor internally so performance will be higher.
+Disruptor internally, so performance will be higher.
== Thread pools
@@ -166,13 +167,14 @@ Can wind up with adding a normal
http://docs.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/BlockingQueue.html[BlockingQueue]
to be used in conjunction with the Disruptor, effectively negating part
of the performance gains achieved by using the Disruptor. Instead, it is
-advices to directly configure number of threads that process messages on
+advices to directly configure the number of threads that process messages on
a Disruptor endpoint using the concurrentConsumers option.
== Sample
-In the route below we use the Disruptor to send the request to this
-async queue to be able to send a fire-and-forget message for further
+In the route below, we use the Disruptor to send the request to this
+async queue.
+As such, it is able to send a _fire-and-forget_ message for further
processing in another thread, and return a constant reply in this thread
to the original caller.
@@ -189,7 +191,7 @@ public void configure() {
}
-------------------------------------------------
-Here we send a Hello World message and expects the reply to be OK.
+Here we send a _Hello World_ message and expect the reply to be _OK_.
[source,java]
-----------------------------------------------------------------
@@ -204,7 +206,7 @@ unit test.
== Using multipleConsumers
-In this example we have defined two consumers and registered them as
+In this example, we have defined two consumers and registered them as
spring beans.
[source,xml]
@@ -221,10 +223,10 @@ spring beans.
-------------------------------------------------------------------------------------------
Since we have specified multipleConsumers=true on the Disruptor foo
-endpoint we can have those two or more consumers receive their own copy
-of the message as a kind of pub-sub style messaging. As the beans are
-part of an unit test they simply send the message to a mock endpoint,
-but notice how we can use @Consume to consume from the Disruptor.
+endpoint, we can have those two or more consumers receive their own copy
+of the message as a kind of _publish/subscriber_ style messaging.
+As the beans are part of a unit test, they simply send the message to a mock endpoint,
+but notice how we can use _@Consume_ to consume from the Disruptor.
[source,java]
-------------------------------------------
diff --git a/components/camel-disruptor/src/main/docs/disruptor-vm-component.adoc b/components/camel-disruptor/src/main/docs/disruptor-vm-component.adoc
index 3ebaa2d4a11..b0964702b29 100644
--- a/components/camel-disruptor/src/main/docs/disruptor-vm-component.adoc
+++ b/components/camel-disruptor/src/main/docs/disruptor-vm-component.adoc
@@ -15,17 +15,18 @@
*{component-header}*
The Disruptor component provides asynchronous
-https://en.wikipedia.org/wiki/Staged_event-driven_architecture[SEDA] behavior much as the
-standard SEDA component, but utilizes a
-https://github.com/LMAX-Exchange/disruptor[Disruptor] instead of a
+https://en.wikipedia.org/wiki/Staged_event-driven_architecture[SEDA] behavior similarly to the
+standard SEDA component.
+However, it uses a https://github.com/LMAX-Exchange/disruptor[Disruptor] instead of a
http://docs.oracle.com/javase/1.5.0/docs/api/java/util/concurrent/BlockingQueue.html[BlockingQueue]
-utilized by the standard xref:seda-component.adoc[SEDA]. Alternatively, a *disruptor-vm:* endpoint is supported by this component. As with the SEDA
-component, buffers of the *disruptor:* endpoints are only visible within
+used by the standard xref:seda-component.adoc[SEDA].
+
+As with the SEDA component, buffers of the Disruptor endpoints are only visible within
a *single* CamelContext and no support is
provided for persistence or recovery. The buffers of the
-**disruptor-vm:** endpoints also provides support for communication
-across CamelContexts instances so you can use this mechanism to
-communicate across web applications (provided that *camel-disruptor.jar*
+**disruptor-vm:** endpoints also provide support for communication
+across CamelContexts instances, so you can use this mechanism to
+communicate across web applications (as long as *camel-disruptor.jar*
is on the *system/boot* classpath).
The main advantage of choosing to use the Disruptor component over the
@@ -35,25 +36,25 @@ consumers. In those cases, significant increases of throughput and
reduction of latency has been observed. Performance in scenarios without
contention is comparable to the SEDA component.
-The Disruptor is implemented with the intention of mimicing the
-behaviour and options of the SEDA component as much as possible.
-The main differences with the them are the following:
+The Disruptor is implemented with the intention of mimicking the
+behavior and options of the SEDA component as much as possible.
+The main differences between them are the following:
* The buffer used is always bounded in size (default 1024 exchanges).
-* As a the buffer is always bouded, the default behaviour for the
+* As the buffer is always bouded, the default behaviour for the
Disruptor is to block while the buffer is full instead of throwing an
-exception. This default behaviour may be configured on the component
+exception. This default behavior may be configured on the component
(see options).
-* The Disruptor enpoints don't implement the BrowsableEndpoint
+* The Disruptor endpoints don't implement the `BrowsableEndpoint`
interface. As such, the exchanges currently in the Disruptor can't be
-retrieved, only the amount of exchanges.
+retrieved, only the number of exchanges.
* The Disruptor requires its consumers (multicasted or otherwise) to be
statically configured. Adding or removing consumers on the fly requires
complete flushing of all pending exchanges in the Disruptor.
* As a result of the reconfiguration: Data sent over a Disruptor is
directly processed and 'gone' if there is at least one consumer, late
joiners only get new exchanges published after they've joined.
-* The *pollTimeout* option is not supported by the Disruptor component.
+* The `pollTimeout` option is not supported by the Disruptor component.
* When a producer blocks on a full Disruptor, it does not respond to
thread interrupts.
@@ -73,10 +74,10 @@ for this component:
== URI format
--------------------------------
- disruptor-vm:someName[?options]
+ disruptor-vm:someId[?options]
--------------------------------
-Where **someName** can be any string that uniquely identifies the
+Where _someId_ can be any string that uniquely identifies the
endpoint within the current CamelContext.
== Options
@@ -94,7 +95,7 @@ include::partial$component-endpoint-options.adoc[]
== More Documentation
-See the disruptor component for more information
+See the xref:disruptor-component.adoc[Disruptor] component for more information.
// shared with disruptor