org.onosproject.store.service

Interface WorkQueue<E>

Type Parameters:

E - task payload type.

All Superinterfaces:

DistributedPrimitive

public interface WorkQueue<E>
extends DistributedPrimitive

Distributed Work Queue primitive.

Work queue serves as a buffer allowing producers to add tasks and consumers to take tasks to process.

In the system each task is tracked via its unique task identifier which is returned when a task is taken. Work queue guarantees that a task can be taken by only one consumer at a time. Once it finishes processing a consumer must invoke the complete method to mark the task(s) as completed. Tasks thus completed are removed from the queue. If a consumer unexpectedly terminates before it can complete all its tasks are returned back to the queue so that other consumers can pick them up. Since there is a distinct possibility that tasks could be processed more than once (under failure conditions), care should be taken to ensure task processing logic is idempotent.

Nested Class Summary

Nested classes/interfaces inherited from interface org.onosproject.store.service.DistributedPrimitive

DistributedPrimitive.Status, DistributedPrimitive.Type

Field Summary

Fields inherited from interface org.onosproject.store.service.DistributedPrimitive

DEFAULT_OPERATION_TIMEOUT_MILLIS, DEFAULT_OPERTATION_TIMEOUT_MILLIS

Method Summary

Modifier and Type	Method and Description
java.util.concurrent.CompletableFuture<java.lang.Void>	addMultiple(java.util.Collection<E> items) Adds a collection of tasks to the work queue.
default java.util.concurrent.CompletableFuture<java.lang.Void>	addOne(E item) Adds a single task to the work queue.
java.util.concurrent.CompletableFuture<java.lang.Void>	complete(java.util.Collection<java.lang.String> taskIds) Completes a collection of tasks.
default java.util.concurrent.CompletableFuture<java.lang.Void>	complete(java.lang.String... taskIds) Completes a collection of tasks.
default DistributedPrimitive.Type	primitiveType() Returns the type of primitive.
java.util.concurrent.CompletableFuture<java.lang.Void>	registerTaskProcessor(java.util.function.Consumer<E> taskProcessor, int parallelism, java.util.concurrent.Executor executor) Registers a task processing callback to be automatically invoked when new tasks are added to the work queue.
java.util.concurrent.CompletableFuture<WorkQueueStats>	stats() Returns work queue statistics.
java.util.concurrent.CompletableFuture<java.lang.Void>	stopProcessing() Stops automatically processing tasks from work queue.
default java.util.concurrent.CompletableFuture<Task<E>>	take() Picks up a single task from the work queue to work on.
java.util.concurrent.CompletableFuture<java.util.Collection<Task<E>>>	take(int maxItems) Picks up multiple tasks from the work queue to work on.

Methods inherited from interface org.onosproject.store.service.DistributedPrimitive

addStatusChangeListener, applicationId, destroy, name, removeStatusChangeListener, statusChangeListeners

Method Detail

primitiveType

default DistributedPrimitive.Type primitiveType()

Description copied from interface: DistributedPrimitive

Returns the type of primitive.

Specified by:

primitiveType in interface DistributedPrimitive

Returns:

primitive type

addMultiple

java.util.concurrent.CompletableFuture<java.lang.Void> addMultiple(java.util.Collection<E> items)

Adds a collection of tasks to the work queue.

Parameters:

items - collection of task items

Returns:

future that is completed when the operation completes

take

java.util.concurrent.CompletableFuture<java.util.Collection<Task<E>>> take(int maxItems)

Picks up multiple tasks from the work queue to work on.

Tasks that are taken remain invisible to other consumers as long as the consumer stays alive. If a consumer unexpectedly terminates before completing the task, the task becomes visible again to other consumers to process.

Parameters:

maxItems - maximum number of items to take from the queue. The actual number of tasks returned can be at the max this number

Returns:

future for the tasks. The future can be completed with an empty collection if there are no unassigned tasks in the work queue

complete

java.util.concurrent.CompletableFuture<java.lang.Void> complete(java.util.Collection<java.lang.String> taskIds)

Completes a collection of tasks.

Parameters:

taskIds - ids of tasks to complete

Returns:

future that is completed when the operation completes

registerTaskProcessor

java.util.concurrent.CompletableFuture<java.lang.Void> registerTaskProcessor(java.util.function.Consumer<E> taskProcessor,
                                                                             int parallelism,
                                                                             java.util.concurrent.Executor executor)

Registers a task processing callback to be automatically invoked when new tasks are added to the work queue.

Parameters:

taskProcessor - task processing callback

parallelism - max tasks that can be processed in parallel

executor - executor to use for processing the tasks

Returns:

future that is completed when the operation completes

stopProcessing

java.util.concurrent.CompletableFuture<java.lang.Void> stopProcessing()

Stops automatically processing tasks from work queue. This call nullifies the effect of a previous registerTaskProcessor call.

Returns:

future that is completed when the operation completes

stats

java.util.concurrent.CompletableFuture<WorkQueueStats> stats()

Returns work queue statistics.

Returns:

future that is completed with work queue stats when the operation completes

complete

default java.util.concurrent.CompletableFuture<java.lang.Void> complete(java.lang.String... taskIds)

Completes a collection of tasks.

Parameters:

taskIds - var arg list of task ids

Returns:

future that is completed when the operation completes

addOne

default java.util.concurrent.CompletableFuture<java.lang.Void> addOne(E item)

Adds a single task to the work queue.

Parameters:

item - task item

Returns:

future that is completed when the operation completes

take

default java.util.concurrent.CompletableFuture<Task<E>> take()

Picks up a single task from the work queue to work on.

Tasks that are taken remain invisible to other consumers as long as the consumer stays alive. If a consumer unexpectedly terminates before completing the task, the task becomes visible again to other consumers to process.

Returns:

future for the task. The future can be completed with null, if there are no unassigned tasks in the work queue