diff --git a/src/main/java/com/lmax/disruptor/AbstractSequencer.java b/src/main/java/com/lmax/disruptor/AbstractSequencer.java index 50e057063..9bc45de57 100644 --- a/src/main/java/com/lmax/disruptor/AbstractSequencer.java +++ b/src/main/java/com/lmax/disruptor/AbstractSequencer.java @@ -39,7 +39,7 @@ public abstract class AbstractSequencer implements Sequencer * Create with the specified buffer size and wait strategy. * * @param bufferSize The total number of entries, must be a positive power of 2. - * @param waitStrategy + * @param waitStrategy The wait strategy used by this sequencer */ public AbstractSequencer(int bufferSize, WaitStrategy waitStrategy) { diff --git a/src/main/java/com/lmax/disruptor/EventSink.java b/src/main/java/com/lmax/disruptor/EventSink.java index fe885ebd6..a74718a9c 100644 --- a/src/main/java/com/lmax/disruptor/EventSink.java +++ b/src/main/java/com/lmax/disruptor/EventSink.java @@ -28,6 +28,7 @@ public interface EventSink /** * Allows one user supplied argument. * + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @see #publishEvent(EventTranslator) @@ -37,6 +38,7 @@ public interface EventSink /** * Allows one user supplied argument. * + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @return true if the value was published, false if there was insufficient @@ -48,6 +50,8 @@ public interface EventSink /** * Allows two user supplied arguments. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @param arg1 A user supplied argument. @@ -58,6 +62,8 @@ public interface EventSink /** * Allows two user supplied arguments. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @param arg1 A user supplied argument. @@ -70,6 +76,9 @@ public interface EventSink /** * Allows three user supplied arguments * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @param arg1 A user supplied argument. @@ -81,6 +90,9 @@ public interface EventSink /** * Allows three user supplied arguments * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @param arg1 A user supplied argument. @@ -112,30 +124,30 @@ public interface EventSink boolean tryPublishEvent(EventTranslatorVararg translator, Object... args); /** - * Publishes multiple events to the ring buffer. It handles + *

Publishes multiple events to the ring buffer. It handles * claiming the next sequence, getting the current (uninitialised) * event from the ring buffer and publishing the claimed sequence - * after translation. - *

- * With this call the data that is to be inserted into the ring + * after translation.

+ * + *

With this call the data that is to be inserted into the ring * buffer will be a field (either explicitly or captured anonymously), * therefore this call will require an instance of the translator - * for each value that is to be inserted into the ring buffer. + * for each value that is to be inserted into the ring buffer.

* * @param translators The user specified translation for each event */ void publishEvents(EventTranslator[] translators); /** - * Publishes multiple events to the ring buffer. It handles + *

Publishes multiple events to the ring buffer. It handles * claiming the next sequence, getting the current (uninitialised) * event from the ring buffer and publishing the claimed sequence - * after translation. - *

- * With this call the data that is to be inserted into the ring + * after translation.

+ * + *

With this call the data that is to be inserted into the ring * buffer will be a field (either explicitly or captured anonymously), * therefore this call will require an instance of the translator - * for each value that is to be inserted into the ring buffer. + * for each value that is to be inserted into the ring buffer.

* * @param translators The user specified translation for each event * @param batchStartsAt The first element of the array which is within the batch. @@ -174,6 +186,7 @@ public interface EventSink /** * Allows one user supplied argument per event. * + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 A user supplied argument. * @see #publishEvents(com.lmax.disruptor.EventTranslator[]) @@ -183,6 +196,7 @@ public interface EventSink /** * Allows one user supplied argument per event. * + * @param Class of the user supplied argument * @param translator The user specified translation for each event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The actual size of the batch @@ -194,6 +208,7 @@ public interface EventSink /** * Allows one user supplied argument. * + * @param Class of the user supplied argument * @param translator The user specified translation for each event * @param arg0 An array of user supplied arguments, one element per event. * @return true if the value was published, false if there was insufficient @@ -205,6 +220,7 @@ public interface EventSink /** * Allows one user supplied argument. * + * @param Class of the user supplied argument * @param translator The user specified translation for each event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The actual size of the batch @@ -218,6 +234,8 @@ public interface EventSink /** * Allows two user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 An array of user supplied arguments, one element per event. * @param arg1 An array of user supplied arguments, one element per event. @@ -228,6 +246,8 @@ public interface EventSink /** * Allows two user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The actual size of the batch. @@ -242,6 +262,8 @@ void publishEvents( /** * Allows two user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 An array of user supplied arguments, one element per event. * @param arg1 An array of user supplied arguments, one element per event. @@ -254,6 +276,8 @@ void publishEvents( /** * Allows two user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The actual size of the batch. @@ -270,6 +294,9 @@ boolean tryPublishEvents( /** * Allows three user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 An array of user supplied arguments, one element per event. * @param arg1 An array of user supplied arguments, one element per event. @@ -281,6 +308,9 @@ boolean tryPublishEvents( /** * Allows three user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The number of elements in the batch. @@ -296,6 +326,9 @@ void publishEvents( /** * Allows three user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param arg0 An array of user supplied arguments, one element per event. * @param arg1 An array of user supplied arguments, one element per event. @@ -309,6 +342,9 @@ void publishEvents( /** * Allows three user supplied arguments per event. * + * @param Class of the user supplied argument + * @param Class of the user supplied argument + * @param Class of the user supplied argument * @param translator The user specified translation for the event * @param batchStartsAt The first element of the array which is within the batch. * @param batchSize The actual size of the batch. diff --git a/src/main/java/com/lmax/disruptor/EventTranslator.java b/src/main/java/com/lmax/disruptor/EventTranslator.java index c87c29abc..07ca169fc 100644 --- a/src/main/java/com/lmax/disruptor/EventTranslator.java +++ b/src/main/java/com/lmax/disruptor/EventTranslator.java @@ -17,7 +17,7 @@ /** *

Implementations translate (write) data representations into events claimed from the {@link RingBuffer}.

- *

+ * *

When publishing to the RingBuffer, provide an EventTranslator. The RingBuffer will select the next available * event by sequence and provide it to the EventTranslator (which should update the event), before publishing * the sequence update.

diff --git a/src/main/java/com/lmax/disruptor/ExceptionHandler.java b/src/main/java/com/lmax/disruptor/ExceptionHandler.java index a3fb8947a..99bc77ba2 100644 --- a/src/main/java/com/lmax/disruptor/ExceptionHandler.java +++ b/src/main/java/com/lmax/disruptor/ExceptionHandler.java @@ -22,7 +22,7 @@ public interface ExceptionHandler { /** *

Strategy for handling uncaught exceptions when processing an event.

- *

+ * *

If the strategy wishes to terminate further processing by the {@link BatchEventProcessor} * then it should throw a {@link RuntimeException}.

* diff --git a/src/main/java/com/lmax/disruptor/InsufficientCapacityException.java b/src/main/java/com/lmax/disruptor/InsufficientCapacityException.java index 157dd53aa..c15960dcb 100644 --- a/src/main/java/com/lmax/disruptor/InsufficientCapacityException.java +++ b/src/main/java/com/lmax/disruptor/InsufficientCapacityException.java @@ -18,9 +18,9 @@ /** *

Exception thrown when it is not possible to insert a value into * the ring buffer without it wrapping the consuming sequences. Used - * specifically when claiming with the {@link RingBuffer#tryNext()} call. - *

- *

For efficiency this exception will not have a stack trace. + * specifically when claiming with the {@link RingBuffer#tryNext()} call.

+ * + *

For efficiency this exception will not have a stack trace.

*/ @SuppressWarnings("serial") public final class InsufficientCapacityException extends Exception diff --git a/src/main/java/com/lmax/disruptor/MultiProducerSequencer.java b/src/main/java/com/lmax/disruptor/MultiProducerSequencer.java index e442d4286..0b1b50ce0 100644 --- a/src/main/java/com/lmax/disruptor/MultiProducerSequencer.java +++ b/src/main/java/com/lmax/disruptor/MultiProducerSequencer.java @@ -25,10 +25,10 @@ /** *

Coordinator for claiming sequences for access to a data structure while tracking dependent {@link Sequence}s. * Suitable for use for sequencing across multiple publisher threads.

- *

- *

*

Note on {@link Sequencer#getCursor()}: With this sequencer the cursor value is updated after the call + * + *

* Note on {@link Sequencer#getCursor()}: With this sequencer the cursor value is updated after the call * to {@link Sequencer#next()}, to determine the highest available sequence that can be read, then - * {@link Sequencer#getHighestPublishedSequence(long, long)} should be used. + * {@link Sequencer#getHighestPublishedSequence(long, long)} should be used.

*/ public final class MultiProducerSequencer extends AbstractSequencer { diff --git a/src/main/java/com/lmax/disruptor/PhasedBackoffWaitStrategy.java b/src/main/java/com/lmax/disruptor/PhasedBackoffWaitStrategy.java index 155efca0d..72b5c9e1b 100644 --- a/src/main/java/com/lmax/disruptor/PhasedBackoffWaitStrategy.java +++ b/src/main/java/com/lmax/disruptor/PhasedBackoffWaitStrategy.java @@ -19,7 +19,7 @@ /** *

Phased wait strategy for waiting {@link EventProcessor}s on a barrier.

- *

+ * *

This strategy can be used when throughput and low-latency are not as important as CPU resource. * Spins, then yields, then waits using the configured fallback WaitStrategy.

*/ @@ -42,7 +42,12 @@ public PhasedBackoffWaitStrategy( } /** - * Block with wait/notifyAll semantics + * Construct {@link PhasedBackoffWaitStrategy} with fallback to {@link BlockingWaitStrategy} + * + * @param spinTimeout The maximum time in to busy spin for. + * @param yieldTimeout The maximum time in to yield for. + * @param units Time units used for the timeout values. + * @return The constructed wait strategy. */ public static PhasedBackoffWaitStrategy withLock( long spinTimeout, @@ -55,7 +60,12 @@ public static PhasedBackoffWaitStrategy withLock( } /** - * Block with wait/notifyAll semantics + * Construct {@link PhasedBackoffWaitStrategy} with fallback to {@link LiteBlockingWaitStrategy} + * + * @param spinTimeout The maximum time in to busy spin for. + * @param yieldTimeout The maximum time in to yield for. + * @param units Time units used for the timeout values. + * @return The constructed wait strategy. */ public static PhasedBackoffWaitStrategy withLiteLock( long spinTimeout, @@ -68,7 +78,12 @@ public static PhasedBackoffWaitStrategy withLiteLock( } /** - * Block by sleeping in a loop + * Construct {@link PhasedBackoffWaitStrategy} with fallback to {@link SleepingWaitStrategy} + * + * @param spinTimeout The maximum time in to busy spin for. + * @param yieldTimeout The maximum time in to yield for. + * @param units Time units used for the timeout values. + * @return The constructed wait strategy. */ public static PhasedBackoffWaitStrategy withSleep( long spinTimeout, diff --git a/src/main/java/com/lmax/disruptor/RingBuffer.java b/src/main/java/com/lmax/disruptor/RingBuffer.java index 667b545a3..e9df321e1 100644 --- a/src/main/java/com/lmax/disruptor/RingBuffer.java +++ b/src/main/java/com/lmax/disruptor/RingBuffer.java @@ -122,9 +122,11 @@ public final class RingBuffer extends RingBufferFields implements Cursored /** * Create a new multiple producer RingBuffer with the specified wait strategy. * + * @param Class of the event stored in the ring buffer. * @param factory used to create the events within the ring buffer. * @param bufferSize number of elements to create within the ring buffer. * @param waitStrategy used to determine how to wait for new elements to become available. + * @return a constructed ring buffer. * @throws IllegalArgumentException if bufferSize is less than 1 or not a power of 2 * @see MultiProducerSequencer */ @@ -141,8 +143,10 @@ public static RingBuffer createMultiProducer( /** * Create a new multiple producer RingBuffer using the default wait strategy {@link BlockingWaitStrategy}. * + * @param Class of the event stored in the ring buffer. * @param factory used to create the events within the ring buffer. * @param bufferSize number of elements to create within the ring buffer. + * @return a constructed ring buffer. * @throws IllegalArgumentException if bufferSize is less than 1 or not a power of 2 * @see MultiProducerSequencer */ @@ -154,9 +158,11 @@ public static RingBuffer createMultiProducer(EventFactory factory, int /** * Create a new single producer RingBuffer with the specified wait strategy. * + * @param Class of the event stored in the ring buffer. * @param factory used to create the events within the ring buffer. * @param bufferSize number of elements to create within the ring buffer. * @param waitStrategy used to determine how to wait for new elements to become available. + * @return a constructed ring buffer. * @throws IllegalArgumentException if bufferSize is less than 1 or not a power of 2 * @see SingleProducerSequencer */ @@ -173,8 +179,10 @@ public static RingBuffer createSingleProducer( /** * Create a new single producer RingBuffer using the default wait strategy {@link BlockingWaitStrategy}. * + * @param Class of the event stored in the ring buffer. * @param factory used to create the events within the ring buffer. * @param bufferSize number of elements to create within the ring buffer. + * @return a constructed ring buffer. * @throws IllegalArgumentException if bufferSize is less than 1 or not a power of 2 * @see MultiProducerSequencer */ @@ -186,10 +194,12 @@ public static RingBuffer createSingleProducer(EventFactory factory, in /** * Create a new Ring Buffer with the specified producer type (SINGLE or MULTI) * + * @param Class of the event stored in the ring buffer. * @param producerType producer type to use {@link ProducerType}. * @param factory used to create events within the ring buffer. * @param bufferSize number of elements to create within the ring buffer. * @param waitStrategy used to determine how to wait for new elements to become available. + * @return a constructed ring buffer. * @throws IllegalArgumentException if bufferSize is less than 1 or not a power of 2 */ public static RingBuffer create( @@ -211,11 +221,11 @@ public static RingBuffer create( /** *

Get the event for a given sequence in the RingBuffer.

- *

+ * *

This call has 2 uses. Firstly use this call when publishing to a ring buffer. * After calling {@link RingBuffer#next()} use this call to get hold of the * preallocated event to fill with data before calling {@link RingBuffer#publish(long)}.

- *

+ * *

Secondly use this call when consuming data from the ring buffer. After calling * {@link SequenceBarrier#waitFor(long)} call this method with any value greater than * that your current consumer sequence and less than or equal to the value returned from @@ -269,7 +279,7 @@ public long next(int n) /** *

Increment and return the next sequence for the ring buffer. Calls of this - * method should ensure that they always publish the sequence afterward. E.g. + * method should ensure that they always publish the sequence afterward. E.g.

* 
      * long sequence = ringBuffer.next();
      * try {
@@ -280,7 +290,7 @@ public long next(int n)
      * }
      *
*

This method will not block if there is not space available in the ring - * buffer, instead it will throw an {@link InsufficientCapacityException}. + * buffer, instead it will throw an {@link InsufficientCapacityException}.

* * @return The next sequence to publish to. * @throws InsufficientCapacityException if the necessary space in the ring buffer is not available @@ -401,7 +411,7 @@ public SequenceBarrier newBarrier(Sequence... sequencesToTrack) /** * Creates an event poller for this ring buffer gated on the supplied sequences. * - * @param gatingSequences + * @param gatingSequences to be gated on. * @return A poller that will gate on this ring buffer and the supplied sequences. */ public EventPoller newPoller(Sequence... gatingSequences) diff --git a/src/main/java/com/lmax/disruptor/SequenceBarrier.java b/src/main/java/com/lmax/disruptor/SequenceBarrier.java index 8ce8cf52c..cfa25dcf9 100644 --- a/src/main/java/com/lmax/disruptor/SequenceBarrier.java +++ b/src/main/java/com/lmax/disruptor/SequenceBarrier.java @@ -29,7 +29,7 @@ public interface SequenceBarrier * @return the sequence up to which is available * @throws AlertException if a status change has occurred for the Disruptor * @throws InterruptedException if the thread needs awaking on a condition variable. - * @throws TimeoutException + * @throws TimeoutException if a timeout occurs while waiting for the supplied sequence. */ long waitFor(long sequence) throws AlertException, InterruptedException, TimeoutException; diff --git a/src/main/java/com/lmax/disruptor/Sequenced.java b/src/main/java/com/lmax/disruptor/Sequenced.java index b9f028473..b6d808bd2 100644 --- a/src/main/java/com/lmax/disruptor/Sequenced.java +++ b/src/main/java/com/lmax/disruptor/Sequenced.java @@ -56,7 +56,7 @@ public interface Sequenced * available. * * @return the claimed sequence value - * @throws InsufficientCapacityException + * @throws InsufficientCapacityException thrown if there is no space available in the ring buffer. */ long tryNext() throws InsufficientCapacityException; @@ -68,14 +68,14 @@ public interface Sequenced * * @param n the number of sequences to claim * @return the claimed sequence value - * @throws InsufficientCapacityException + * @throws InsufficientCapacityException thrown if there is no space available in the ring buffer. */ long tryNext(int n) throws InsufficientCapacityException; /** * Publishes a sequence. Call when the event has been filled. * - * @param sequence + * @param sequence the sequence to be published. */ void publish(long sequence); diff --git a/src/main/java/com/lmax/disruptor/Sequencer.java b/src/main/java/com/lmax/disruptor/Sequencer.java index 914b4c053..cf1b5dd5f 100644 --- a/src/main/java/com/lmax/disruptor/Sequencer.java +++ b/src/main/java/com/lmax/disruptor/Sequencer.java @@ -61,7 +61,7 @@ public interface Sequencer extends Cursored, Sequenced * Create a new SequenceBarrier to be used by an EventProcessor to track which messages * are available to be read from the ring buffer given a list of sequences to track. * - * @param sequencesToTrack + * @param sequencesToTrack All of the sequences that the newly constructed barrier will wait on. * @return A sequence barrier that will track the specified sequences. * @see SequenceBarrier */ diff --git a/src/main/java/com/lmax/disruptor/SingleProducerSequencer.java b/src/main/java/com/lmax/disruptor/SingleProducerSequencer.java index 800eb9173..6f2063ab6 100644 --- a/src/main/java/com/lmax/disruptor/SingleProducerSequencer.java +++ b/src/main/java/com/lmax/disruptor/SingleProducerSequencer.java @@ -46,9 +46,9 @@ public SingleProducerSequencerFields(int bufferSize, WaitStrategy waitStrategy) /** *

Coordinator for claiming sequences for access to a data structure while tracking dependent {@link Sequence}s. * Not safe for use from multiple threads as it does not implement any barriers.

- *

- *

Note on {@link Sequencer#getCursor()}: With this sequencer the cursor value is updated after the call - * to {@link Sequencer#publish(long)} is made. + * + *

* Note on {@link Sequencer#getCursor()}: With this sequencer the cursor value is updated after the call + * to {@link Sequencer#publish(long)} is made.

*/ public final class SingleProducerSequencer extends SingleProducerSequencerFields diff --git a/src/main/java/com/lmax/disruptor/WaitStrategy.java b/src/main/java/com/lmax/disruptor/WaitStrategy.java index a7f4a9aa2..f7bd90f44 100644 --- a/src/main/java/com/lmax/disruptor/WaitStrategy.java +++ b/src/main/java/com/lmax/disruptor/WaitStrategy.java @@ -36,7 +36,7 @@ public interface WaitStrategy * @return the sequence that is available which may be greater than the requested sequence. * @throws AlertException if the status of the Disruptor has changed. * @throws InterruptedException if the thread is interrupted. - * @throws TimeoutException + * @throws TimeoutException if a timeout occurs before waiting completes (not used by some strategies) */ long waitFor(long sequence, Sequence cursor, Sequence dependentSequence, SequenceBarrier barrier) throws AlertException, InterruptedException, TimeoutException; diff --git a/src/main/java/com/lmax/disruptor/WorkProcessor.java b/src/main/java/com/lmax/disruptor/WorkProcessor.java index 71e76abb3..aa8efe117 100644 --- a/src/main/java/com/lmax/disruptor/WorkProcessor.java +++ b/src/main/java/com/lmax/disruptor/WorkProcessor.java @@ -20,7 +20,7 @@ /** *

A {@link WorkProcessor} wraps a single {@link WorkHandler}, effectively consuming the sequence * and ensuring appropriate barriers.

- *

+ * *

Generally, this will be used as part of a {@link WorkerPool}.

* * @param event implementation storing the details for the work to processed. diff --git a/src/main/java/com/lmax/disruptor/collections/Histogram.java b/src/main/java/com/lmax/disruptor/collections/Histogram.java index 65933b32d..27697c97d 100644 --- a/src/main/java/com/lmax/disruptor/collections/Histogram.java +++ b/src/main/java/com/lmax/disruptor/collections/Histogram.java @@ -21,10 +21,10 @@ /** *

Histogram for tracking the frequency of observations of values below interval upper bounds.

- *

+ * *

This class is useful for recording timings across a large number of observations - * when high performance is required.

- *

+ * when high performance is required.

+ * *

The interval bounds are used to define the ranges of the histogram buckets. If provided bounds * are [10,20,30,40,50] then there will be five buckets, accessible by index 0-4. Any value * 0-10 will fall into the first interval bar, values 11-20 will fall into the @@ -171,7 +171,7 @@ private void trackRange(final long value) /** *

Add observations from another Histogram into this one.

- *

+ * *

Histograms must have the same intervals.

* * @param histogram from which to add the observation counts. @@ -257,7 +257,7 @@ public long getMax() /** *

Calculate the mean of all recorded observations.

- *

+ * *

The mean is calculated by summing the mid points of each interval multiplied by the count * for that interval, then dividing by the total count of observations. The max and min are * considered for adjusting the top and bottom bin when calculating the mid point, this @@ -322,7 +322,7 @@ public long getFourNinesUpperBound() /** *

Get the interval upper bound for a given factor of the observation population.

- *

+ * *

Note this does not get the actual percentile measurement, it only gets the bucket

* * @param factor representing the size of the population. diff --git a/src/main/java/com/lmax/disruptor/dsl/Disruptor.java b/src/main/java/com/lmax/disruptor/dsl/Disruptor.java index 4dd08e6fe..e1b9e5a85 100644 --- a/src/main/java/com/lmax/disruptor/dsl/Disruptor.java +++ b/src/main/java/com/lmax/disruptor/dsl/Disruptor.java @@ -39,14 +39,11 @@ import java.util.concurrent.atomic.AtomicBoolean; /** - * A DSL-style API for setting up the disruptor pattern around a ring buffer - * (aka the Builder pattern). - *

- *

- * A simple example of setting up the disruptor with two event handlers that - * must process events in order: - *

- *

+ *

A DSL-style API for setting up the disruptor pattern around a ring buffer + * (aka the Builder pattern).

+ * + *

A simple example of setting up the disruptor with two event handlers that + * must process events in order:

* 
  * Disruptor<MyEvent> disruptor = new Disruptor<MyEvent>(MyEvent.FACTORY, 32, Executors.newCachedThreadPool());
  * EventHandler<MyEvent> handler1 = new EventHandler<MyEvent>() { ... };
@@ -153,7 +150,7 @@ private Disruptor(final RingBuffer ringBuffer, final Executor executor)
     /**
      * 
Set up event handlers to handle events from the ring buffer. These handlers will process events
      * as soon as they become available, in parallel.

-     * 

+     *
      * 
This method can be used as the start of a chain. For example if the handler A must
      * process events before handler B:

      * 
dw.handleEventsWith(A).then(B);

@@ -170,11 +167,11 @@ public EventHandlerGroup handleEventsWith(final EventHandler... ha
     /**
      * 
Set up custom event processors to handle events from the ring buffer. The Disruptor will
      * automatically start these processors when {@link #start()} is called.

-     * 

+     *
      * 
This method can be used as the start of a chain. For example if the handler A must
      * process events before handler B:

      * 
dw.handleEventsWith(A).then(B);

-     * 

+     *
      * 
Since this is the start of the chain, the processor factories will always be passed an empty Sequence
      * array, so the factory isn't necessary in this case. This method is provided for consistency with
      * {@link EventHandlerGroup#handleEventsWith(EventProcessorFactory...)} and {@link EventHandlerGroup#then(EventProcessorFactory...)}
@@ -192,7 +189,7 @@ public EventHandlerGroup handleEventsWith(final EventProcessorFactory... e
     /**
      * 
Set up custom event processors to handle events from the ring buffer. The Disruptor will
      * automatically start this processors when {@link #start()} is called.

-     * 

+     *
      * 
This method can be used as the start of a chain. For example if the processor A must
      * process events before handler B:

      * 
dw.handleEventsWith(A).then(B);

@@ -235,7 +232,7 @@ public EventHandlerGroup handleEventsWithWorkerPool(final WorkHandler... w
 
     /**
      * 
Specify an exception handler to be used for any future event handlers.

-     * 

+     *
      * 
Note that only event handlers set up after calling this method will use the exception handler.

      *
      * @param exceptionHandler the exception handler to use for any future {@link EventProcessor}.
@@ -248,7 +245,7 @@ public void handleExceptionsWith(final ExceptionHandler exceptionHand
 
     /**
      * 
Specify an exception handler to be used for event handlers and worker pools created by this Disruptor.

-     * 

+     *
      * 
The exception handler will be used by existing and future event handlers and worker pools created by this Disruptor instance.

      *
      * @param exceptionHandler the exception handler to use.
@@ -279,7 +276,7 @@ public ExceptionHandlerSetting handleExceptionsFor(final EventHandler even
     /**
      * 
Create a group of event handlers to be used as a dependency.
      * For example if the handler A must process events before handler B:

-     * 

+     *
      * 
dw.after(A).handleEventsWith(B);

      *
      * @param handlers the event handlers, previously set up with {@link #handleEventsWith(com.lmax.disruptor.EventHandler[])},
@@ -329,6 +326,7 @@ public void publishEvent(final EventTranslator eventTranslator)
     /**
      * Publish an event to the ring buffer.
      *
+     * @param  Class of the user supplied argument.
      * @param eventTranslator the translator that will load data into the event.
      * @param arg             A single argument to load into the event
      */
@@ -340,6 +338,7 @@ public  void publishEvent(final EventTranslatorOneArg eventTranslator,
     /**
      * Publish a batch of events to the ring buffer.
      *
+     * @param  Class of the user supplied argument.
      * @param eventTranslator the translator that will load data into the event.
      * @param arg             An array single arguments to load into the events. One Per event.
      */
@@ -351,6 +350,8 @@ public  void publishEvents(final EventTranslatorOneArg eventTranslator,
     /**
      * Publish an event to the ring buffer.
      *
+     * @param  Class of the user supplied argument.
+     * @param  Class of the user supplied argument.
      * @param eventTranslator the translator that will load data into the event.
      * @param arg0            The first argument to load into the event
      * @param arg1            The second argument to load into the event
@@ -364,6 +365,9 @@ public  void publishEvent(final EventTranslatorTwoArg eventTransl
      * Publish an event to the ring buffer.
      *
      * @param eventTranslator the translator that will load data into the event.
+     * @param  Class of the user supplied argument.
+     * @param  Class of the user supplied argument.
+     * @param  Class of the user supplied argument.
      * @param arg0            The first argument to load into the event
      * @param arg1            The second argument to load into the event
      * @param arg2            The third argument to load into the event
@@ -375,10 +379,10 @@ public  void publishEvent(final EventTranslatorThreeArg eve
 
     /**
      * 
Starts the event processors and returns the fully configured ring buffer.

-     * 

+     *
      * 
The ring buffer is set up to prevent overwriting any entry that is yet to
      * be processed by the slowest event processor.

-     * 

+     *
      * 
This method must only be called once after all event processors have been added.

      *
      * @return the configured ring buffer.
@@ -406,10 +410,10 @@ public void halt()
     }
 
     /**
-     * Waits until all events currently in the disruptor have been processed by all event processors
+     * 
Waits until all events currently in the disruptor have been processed by all event processors
      * and then halts the processors.  It is critical that publishing to the ring buffer has stopped
-     * before calling this method, otherwise it may never return.
-     * 

+     * before calling this method, otherwise it may never return.

+     *
      * 
This method will not shutdown the executor, nor will it await the final termination of the
      * processor threads.

      */
@@ -428,12 +432,13 @@ public void shutdown()
     /**
      * 
Waits until all events currently in the disruptor have been processed by all event processors
      * and then halts the processors.

-     * 

+     *
      * 
This method will not shutdown the executor, nor will it await the final termination of the
      * processor threads.

      *
      * @param timeout  the amount of time to wait for all events to be processed. -1 will give an infinite timeout
      * @param timeUnit the unit the timeOut is specified in
+     * @throws TimeoutException if a timeout occurs before shutdown completes.
      */
     public void shutdown(final long timeout, final TimeUnit timeUnit) throws TimeoutException
     {
@@ -508,8 +513,8 @@ public SequenceBarrier getBarrierFor(final EventHandler handler)
     /**
      * Gets the sequence value for the specified event handlers.
      *
-     * @param b1
-     * @return
+     * @param b1 eventHandler to get the sequence for.
+     * @return eventHandler's sequence
      */
     public long getSequenceValueFor(final EventHandler b1)
     {
diff --git a/src/main/java/com/lmax/disruptor/dsl/EventHandlerGroup.java b/src/main/java/com/lmax/disruptor/dsl/EventHandlerGroup.java
index c8fe91d3c..e5b4cea7e 100644
--- a/src/main/java/com/lmax/disruptor/dsl/EventHandlerGroup.java
+++ b/src/main/java/com/lmax/disruptor/dsl/EventHandlerGroup.java
@@ -81,12 +81,12 @@ public EventHandlerGroup and(final EventProcessor... processors)
     }
 
     /**
-     * Set up batch handlers to consume events from the ring buffer. These handlers will only process events
-     * after every {@link EventProcessor} in this group has processed the event.
-     * 

+     * 
Set up batch handlers to consume events from the ring buffer. These handlers will only process events
+     * after every {@link EventProcessor} in this group has processed the event.

+     *
      * 
This method is generally used as part of a chain. For example if the handler A must
      * process events before handler B:

-     * 

+     *
      * 
dw.handleEventsWith(A).then(B);

      *
      * @param handlers the batch handlers that will process events.
@@ -100,7 +100,7 @@ public EventHandlerGroup then(final EventHandler... handlers)
     /**
      * 
Set up custom event processors to handle events from the ring buffer. The Disruptor will
      * automatically start these processors when {@link Disruptor#start()} is called.

-     * 

+     *
      * 
This method is generally used as part of a chain. For example if the handler A must
      * process events before handler B:

      *
@@ -113,13 +113,13 @@ public EventHandlerGroup then(final EventProcessorFactory... eventProcesso
     }
 
     /**
-     * Set up a worker pool to handle events from the ring buffer. The worker pool will only process events
+     * 
Set up a worker pool to handle events from the ring buffer. The worker pool will only process events
      * after every {@link EventProcessor} in this group has processed the event. Each event will be processed
-     * by one of the work handler instances.
-     * 

+     * by one of the work handler instances.

+     *
      * 
This method is generally used as part of a chain. For example if the handler A must
      * process events before the worker pool with handlers B, C:

-     * 

+     *
      * 
dw.handleEventsWith(A).thenHandleEventsWithWorkerPool(B, C);

      *
      * @param handlers the work handlers that will process events. Each work handler instance will provide an extra thread in the worker pool.
@@ -131,12 +131,12 @@ public EventHandlerGroup thenHandleEventsWithWorkerPool(final WorkHandler
+     * 
Set up batch handlers to handle events from the ring buffer. These handlers will only process events
+     * after every {@link EventProcessor} in this group has processed the event.

+     *
      * 
This method is generally used as part of a chain. For example if A must
      * process events before B:

-     * 

+     *
      * 
dw.after(A).handleEventsWith(B);

      *
      * @param handlers the batch handlers that will process events.
@@ -150,10 +150,10 @@ public EventHandlerGroup handleEventsWith(final EventHandler... ha
     /**
      * 
Set up custom event processors to handle events from the ring buffer. The Disruptor will
      * automatically start these processors when {@link Disruptor#start()} is called.

-     * 

+     *
      * 
This method is generally used as part of a chain. For example if A must
      * process events before B:

-     * 

+     *
      * 
dw.after(A).handleEventsWith(B);

      *
      * @param eventProcessorFactories the event processor factories to use to create the event processors that will process events.
@@ -165,13 +165,13 @@ public EventHandlerGroup handleEventsWith(final EventProcessorFactory... e
     }
 
     /**
-     * Set up a worker pool to handle events from the ring buffer. The worker pool will only process events
+     * 
Set up a worker pool to handle events from the ring buffer. The worker pool will only process events
      * after every {@link EventProcessor} in this group has processed the event. Each event will be processed
-     * by one of the work handler instances.
-     * 

+     * by one of the work handler instances.

+     *
      * 
This method is generally used as part of a chain. For example if the handler A must
      * process events before the worker pool with handlers B, C:

-     * 

+     *
      * 
dw.after(A).handleEventsWithWorkerPool(B, C);

      *
      * @param handlers the work handlers that will process events. Each work handler instance will provide an extra thread in the worker pool.
diff --git a/src/main/java/com/lmax/disruptor/dsl/EventProcessorFactory.java b/src/main/java/com/lmax/disruptor/dsl/EventProcessorFactory.java
index 8e5cce5c2..d766f0e7f 100644
--- a/src/main/java/com/lmax/disruptor/dsl/EventProcessorFactory.java
+++ b/src/main/java/com/lmax/disruptor/dsl/EventProcessorFactory.java
@@ -16,6 +16,7 @@ public interface EventProcessorFactory
     /**
      * Create a new event processor that gates on barrierSequences.
      *
+     * @param ringBuffer the ring buffer to receive events from.
      * @param barrierSequences the sequences to gate on
      * @return a new EventProcessor that gates on barrierSequences before processing events
      */
diff --git a/src/main/java/com/lmax/disruptor/util/Util.java b/src/main/java/com/lmax/disruptor/util/Util.java
index 1ef12ca0f..c181f4097 100644
--- a/src/main/java/com/lmax/disruptor/util/Util.java
+++ b/src/main/java/com/lmax/disruptor/util/Util.java
@@ -129,7 +129,7 @@ public static Unsafe getUnsafe()
     /**
      * Gets the address value for the memory that backs a direct byte buffer.
      *
-     * @param buffer
+     * @param buffer a direct buffer to get the address from.
      * @return The system address for the buffers
      */
     public static long getAddressFromDirectByteBuffer(ByteBuffer buffer)