xapi.process.api

Interface AsyncCondition

public interface AsyncCondition

In order to ease the apis of code shared with single-threaded environments, we create an Async abstraction that can function efficiently in a threadsafe enviro, while giving a useful "illusion of concurrency" when single-threaded. It does force a callback pattern onto code that may otherwise have been able to simple block and run in a nice procedural fashion, but it enables a more functional approach, that will scale much better. You do not wait for your work to be finished, you send the rest of work, and it is run for you when the given condition is satisfied (the owner of the lock calls signal().)

Author:

"James X. Nelson (james@wetheinter.net)"

Method Summary

Methods

Modifier and Type	Method and Description
xapi.util.api.RemovalHandler	await(xapi.util.api.SuccessHandler<xapi.util.api.Pair<AsyncLock,AsyncCondition>> onAcquire) Waits indefinitely for the given condition.
xapi.util.api.RemovalHandler	awaitWithDeadline(xapi.util.api.SuccessHandler<xapi.util.api.Pair<AsyncLock,AsyncCondition>> onAcquire, float millisToWait) The same rules as await(SuccessHandler), but with a millisecond timeout that will share a notification pool, so a minimum of threads are needed to simply check deadlines and cancel / notify / continue.
boolean	signal() Signals one waiting success handler, and returns true, -if the pool of waiting conditions was empty BEFORE calling onAcquire.onSuccess-

Method Detail

await

xapi.util.api.RemovalHandler await(xapi.util.api.SuccessHandler<xapi.util.api.Pair<AsyncLock,AsyncCondition>> onAcquire)

Waits indefinitely for the given condition.

Parameters:

onAcquire - - A SuccessHandler to be notified when we are signalled.

Returns:

- A removal handler to cancel the wait if it hasn't already completed. If you want a deadline, use awaitWithDeadline(SuccessHandler, float) If your SuccessHandler is also an ErrorHandler, you will receive a CancellationException when RemovalHandler.remove() is called.

awaitWithDeadline

xapi.util.api.RemovalHandler awaitWithDeadline(xapi.util.api.SuccessHandler<xapi.util.api.Pair<AsyncLock,AsyncCondition>> onAcquire,
                                             float millisToWait)

The same rules as await(SuccessHandler), but with a millisecond timeout that will share a notification pool, so a minimum of threads are needed to simply check deadlines and cancel / notify / continue.

Parameters:

onAcquire - - The success handler to call when we are signalled.

millisToWait - - A floating point number of milliseconds to wait.

Returns:

A RemovalHandler to cancel the operation. Does nothing if signal has already been called.

signal

boolean signal()

Signals one waiting success handler, and returns true, -if the pool of waiting conditions was empty BEFORE calling onAcquire.onSuccess-

Returns:

- True is the waiting pool on SuccessHandlers had, at most one item in it when signal() is called. This can allow a flushing method to safely call while(signal()); to drain a condition.