| Support for transactional enqueue.
This method allows a client to provisionally enqueue a number
of elements onto the queue, and then later commit the enqueue (with
a enqueue_commit() call), or abort (with a
enqueue_abort() call). This mechanism can be used to
perform "split-phase" enqueues, where a client first enqueues a
set of elements on the queue and then performs some work to "fill in"
those elements before performing a commit. This can also be used
to perform multi-queue transactional enqueue operations, with an
"all-or-nothing" strategy for enqueueing events on multiple queues.
This method would generally be used in the following manner:
Object key = sink.enqueue_prepare(someElements);
if (can_commit) {
sink.enqueue_commit(key);
} else {
sink.enqueue_abort(key);
}
Note that this method does not protect against
"dangling prepares" -- that is, a prepare without an associated
commit or abort operation. This method should be used with care.
In particular, be sure that all code paths (such as exceptions)
after a prepare include either a commit or an abort.
Like enqueue_many, enqueue_prepare is an
"all or none" operation: the enqueue predicate must accept all
elements for enqueue, or none of them will be enqueued.
Parameters:
elements - The element array to provisionally enqueue A "transaction key" that may be used to commit or abortthe provisional enqueue
exception:
SinkFullException - Indicates that the sink is temporarily fulland that the requested elements could not be provisionally enqueued.
exception:
SinkClosedException - Indicates that the sink is no longer being serviced.
See Also: enqueue_commit
See Also: enqueue_abort |