ConcurrentConveyor (Hazelcast Root 3.12-BETA-1 API)

java.lang.Object
- com.hazelcast.internal.util.concurrent.ConcurrentConveyor<E>

Direct Known Subclasses:

ConcurrentConveyorSingleQueue
```
public class ConcurrentConveyor<E>
extends Object
```
A many-to-one conveyor of interthread messages. Allows a setup where communication from N submitter threads to 1 drainer thread happens over N one-to-one concurrent queues. Queues are numbered from 0 to N-1 and the queue at index 0 is the default queue. There are some convenience methods which assume the usage of the default queue.
Allows the drainer thread to signal completion and failure to the submitters and make their blocking submit() calls fail with an exception. This mechanism supports building an implementation which is both starvation-safe and uses bounded queues with blocking queue submission.
There is a further option for the drainer to apply immediate backpressure to the submitter by invoking backpressureOn(). This will make the submit() invocations block after having successfully submitted their item, until the drainer calls backpressureOff() or fails. This mechanism allows the drainer to apply backpressure and keep draining the queue, thus letting all submitters progress until after submitting their item. Such an arrangement eliminates a class of deadlock patterns where the submitter blocks to submit the item that would have made the drainer remove backpressure.
Does not manage drainer threads. There should be only one drainer thread at a time.

Usage example
```
 // 1. Set up the concurrent conveyor

 final int queueCapacity = 128;
 final Runnable doneItem = new Runnable() { public void run() {} };
 final QueuedPipe[] qs = new QueuedPipe[2];
 qs[0] = new OneToOneConcurrentArrayQueue(queueCapacity);
 qs[1] = new OneToOneConcurrentArrayQueue(queueCapacity);
 final ConcurrentConveyor conveyor = concurrentConveyor(doneItem, qs);

 // 2. Set up the drainer thread

 final Thread drainer = new Thread(new Runnable() {
     private int submitterGoneCount;
```

Field Summary

Fields
Modifier and Type	Field and Description
`static IdleStrategy`	`SUBMIT_IDLER` Idling strategy used by the `submit()` methods.
`static long`	`SUBMIT_MAX_PARK_MICROS` Max park microseconds while waiting to submit to the work queue.
`static int`	`SUBMIT_SPIN_COUNT` How many times to busy-spin while waiting to submit to the work queue.
`static int`	`SUBMIT_YIELD_COUNT` How many times to yield while waiting to submit to the work queue.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`awaitDrainerGone()` Blocks until the drainer thread leaves.
`void`	`backpressureOff()` Lowers the `backpressure` flag.
`void`	`backpressureOn()` Raises the `backpressure` flag, which will make the caller of `submit` to block until the flag is lowered.
`void`	`checkDrainerGone()` Checks whether the drainer thread has left and throws an exception if it has.
`static <E1> ConcurrentConveyor<E1>`	`concurrentConveyor(E1 submitterGoneItem, QueuedPipe<E1>... queues)` Creates a new concurrent conveyor.
`int`	`drain(int queueIndex, Predicate<? super E> itemHandler)` Drains a batch of items from the queue at the supplied index to the supplied `itemHandler`.
`void`	`drainerArrived()` Called by the drainer thread to signal that it has started draining the queue.
`void`	`drainerDone()` Called by the drainer thread to signal that it is done draining the queue.
`void`	`drainerFailed(Throwable t)` Called by the drainer thread to signal that it has failed and will drain no more items from the queue.
`int`	`drainTo(Collection<? super E> drain)` Drains a batch of items from the default queue into the supplied collection.
`int`	`drainTo(Collection<? super E> drain, int limit)` Drains no more than `limit` items from the default queue into the supplied collection.
`int`	`drainTo(int queueIndex, Collection<? super E> drain)` Drains a batch of items from the queue at the supplied index into the supplied collection.
`int`	`drainTo(int queueIndex, Collection<? super E> drain, int limit)` Drains no more than `limit` items from the queue at the supplied index into the supplied collection.
`boolean`	`isDrainerGone()`
`int`	`liveQueueCount()` Returns the number of remaining live queues, i.e., `queueCount()` minus the number of queues nulled out by calling `removeQueue(int)`.
`boolean`	`offer(int queueIndex, E item)` Offers an item to the queue at the given index.
`boolean`	`offer(Queue<E> queue, E item)` Offers an item to the given queue.
`QueuedPipe<E>`	`queue(int index)`
`int`	`queueCount()` Returns the size of the array holding the concurrent queues.
`boolean`	`removeQueue(int index)`
`void`	`submit(Queue<E> queue, E item)` Blocks until successfully inserting the given item to the given queue.
`E`	`submitterGoneItem()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SUBMIT_SPIN_COUNT
```
public static final int SUBMIT_SPIN_COUNT
```
    How many times to busy-spin while waiting to submit to the work queue.
    
    See Also:
    
    Constant Field Values
  - SUBMIT_YIELD_COUNT
```
public static final int SUBMIT_YIELD_COUNT
```
    How many times to yield while waiting to submit to the work queue.
    
    See Also:
    
    Constant Field Values
  - SUBMIT_MAX_PARK_MICROS
```
public static final long SUBMIT_MAX_PARK_MICROS
```
    Max park microseconds while waiting to submit to the work queue.
    
    See Also:
    
    Constant Field Values
  - SUBMIT_IDLER
```
public static final IdleStrategy SUBMIT_IDLER
```
    Idling strategy used by the submit() methods.
- Method Detail
  - concurrentConveyor
```
public static <E1> ConcurrentConveyor<E1> concurrentConveyor(E1 submitterGoneItem,
                                                             QueuedPipe<E1>... queues)
```
    Creates a new concurrent conveyor.
    
    Parameters:
    
    submitterGoneItem - the object that a submitter thread can use to signal it's done submitting
    
    queues - the concurrent queues the conveyor will manage
  - submitterGoneItem
```
public final E submitterGoneItem()
```
    Returns:
    
    the last item that the submitter thread submits to the conveyor
  - queueCount
```
public final int queueCount()
```
    Returns the size of the array holding the concurrent queues. Initially (when the conveyor is constructed) each array slot should point to a distinct concurrent queue; therefore the size of the array matches the number of queues. Some array slots may be nulled out later by calling removeQueue(int), but this method will keep reporting the same number. The intended use case for this method is giving the upper bound for a loop that iterates over all queues. Since queue indices never change, this number must stay the same.
  - liveQueueCount
```
public final int liveQueueCount()
```
    Returns the number of remaining live queues, i.e., queueCount() minus the number of queues nulled out by calling removeQueue(int).
  - queue
```
public final QueuedPipe<E> queue(int index)
```
    Returns:
    
    the concurrent queue at the given index
  - removeQueue
```
public final boolean removeQueue(int index)
```
  - offer
```
public final boolean offer(int queueIndex,
                           E item)
```
    Offers an item to the queue at the given index.
    
    Returns:
    
    whether the item was accepted by the queue
  - offer
```
public final boolean offer(Queue<E> queue,
                           E item)
                    throws ConcurrentConveyorException
```
    Offers an item to the given queue. No check is performed that the queue actually belongs to this conveyor.
    
    Returns:
    
    whether the item was accepted by the queue
    
    Throws:
    
    ConcurrentConveyorException - if the draining thread has already left
  - submit
```
public final void submit(Queue<E> queue,
                         E item)
                  throws ConcurrentConveyorException
```
    Blocks until successfully inserting the given item to the given queue. No check is performed that the queue actually belongs to this conveyor. If the #backpressure flag is raised on this conveyor at the time the item has been submitted, further blocks until the flag is lowered.
    
    Throws:
    
    ConcurrentConveyorException - if the current thread is interrupted or the draining thread has already left
  - drainTo
```
public final int drainTo(Collection<? super E> drain)
```
    Drains a batch of items from the default queue into the supplied collection.
    
    Returns:
    
    the number of items drained
  - drainTo
```
public final int drainTo(int queueIndex,
                         Collection<? super E> drain)
```
    Drains a batch of items from the queue at the supplied index into the supplied collection.
    
    Returns:
    
    the number of items drained
  - drain
```
public final int drain(int queueIndex,
                       Predicate<? super E> itemHandler)
```
    Drains a batch of items from the queue at the supplied index to the supplied itemHandler. Stops draining, after the itemHandler returns false;
    
    Returns:
    
    the number of items drained
  - drainTo
```
public final int drainTo(Collection<? super E> drain,
                         int limit)
```
    Drains no more than limit items from the default queue into the supplied collection.
    
    Returns:
    
    the number of items drained
  - drainTo
```
public final int drainTo(int queueIndex,
                         Collection<? super E> drain,
                         int limit)
```
    Drains no more than limit items from the queue at the supplied index into the supplied collection.
    
    Returns:
    
    the number of items drained
  - drainerArrived
```
public final void drainerArrived()
```
    Called by the drainer thread to signal that it has started draining the queue.
  - drainerFailed
```
public final void drainerFailed(Throwable t)
```
    Called by the drainer thread to signal that it has failed and will drain no more items from the queue.
    
    Parameters:
    
    t - the drainer's failure
  - drainerDone
```
public final void drainerDone()
```
    Called by the drainer thread to signal that it is done draining the queue.
  - isDrainerGone
```
public final boolean isDrainerGone()
```
    Returns:
    
    whether the drainer thread has left
  - checkDrainerGone
```
public final void checkDrainerGone()
```
    Checks whether the drainer thread has left and throws an exception if it has. If the drainer thread has failed, its failure will be the cause of the exception thrown.
  - awaitDrainerGone
```
public final void awaitDrainerGone()
```
    Blocks until the drainer thread leaves.
  - backpressureOn
```
public final void backpressureOn()
```
    Raises the backpressure flag, which will make the caller of submit to block until the flag is lowered.
  - backpressureOff
```
public final void backpressureOff()
```
    Lowers the backpressure flag.

Class ConcurrentConveyor<E>

Usage example

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SUBMIT_SPIN_COUNT

SUBMIT_YIELD_COUNT

SUBMIT_MAX_PARK_MICROS

SUBMIT_IDLER

Method Detail

concurrentConveyor

submitterGoneItem

queueCount

liveQueueCount

queue

removeQueue

offer

offer

submit

drainTo

drainTo

drain

drainTo

drainTo

drainerArrived

drainerFailed

drainerDone

isDrainerGone

checkDrainerGone

awaitDrainerGone

backpressureOn

backpressureOff