xapi.process.service

Interface ConcurrencyService

All Known Implementing Classes:

ConcurrencyServiceAbstract, ConcurrencyServiceGwt, ConcurrencyServiceJre

public interface ConcurrencyService

Method Summary

Modifier and Type	Method and Description
boolean	flush(Thread thread, int timeout) Flushes all jobs for a given thread, up to a given millisecond timeout.
boolean	kill(Thread thread, int timeout) Flushes all jobs for the given thread, and then kills it.
AsyncLock	newLock()
<T> ProcessController<T>	newProcess(Process<T> process) Experimental; may replace newThread(Runnable).
Thread	newThread(Runnable cmd) Experimental; may be deprecated.
double	now()
<T> void	resolve(Future<T> future, ReceivesValue<T> receiver) Resolves a future in another thread / using a shared poller.
void	runDeferred(Runnable cmd) Runs the given command in a new environment, after all finalies have been processed.
void	runEventually(Runnable cmd) Runs the command eventually, most likely on an unused thread.
void	runFinally(Runnable cmd) Runs the given command after the work queue for the current environment is drained.
void	runTimeout(Runnable cmd, int millisToWait) Wait (at least) a given number of milliseconds to perform a task.
double	threadStartTime(Thread currentThread) Tells what time the current process for the current thread started.
boolean	trySleep(float millis) Attempts to sleep, if the current thread is not interrupted.

Method Detail

newThread

Thread newThread(Runnable cmd)

Experimental; may be deprecated. Creates a new thread for the given runnable. If blacklisting Thread is a problem on some platforms, Thread may be replaced with a proxy class in the public api.

Parameters:

cmd - - The command to wrap in a new thread.

Returns:

- An unstarted thread that will run the given command.

newProcess

<T> ProcessController<T> newProcess(Process<T> process)

Experimental; may replace newThread(Runnable). Accepts an instance of Process, and returns a ProcessController. Designed to give an abstract action-oriented workflow that functions in both threadsafe and singlethreaded environments.

Parameters:

process -

Returns:

runDeferred

void runDeferred(Runnable cmd)

Runs the given command in a new environment, after all finalies have been processed.

Parameters:

cmd - - The task to run.

runFinally

void runFinally(Runnable cmd)

Runs the given command after the work queue for the current environment is drained. Finalies must always be cleared before a given unit of work is truly "finished". You may safely schedule multiple layers of finally blocks from other finally blocks; the queue is copied and reset for every iteration. Just beware that this enforces "single-threadedness", and will cause blocking in a concurrent environment. In GWT, it will not release the processing thread for UI updates until all finalies are complete.

Parameters:

cmd - - The command to run after the work queue is drained.

runTimeout

void runTimeout(Runnable cmd,
                int millisToWait)

Wait (at least) a given number of milliseconds to perform a task. Exact timing promises are not made, so if you need an exact timing in a concurrent environment, schedule your deadline 10-50 millis early, or even better, track latency (how much later you are called then requested) and adjust your timeouts accordingly.

Parameters:

cmd - - The command to run.

millisToWait - - A minimum of milliseconds to wait.

runEventually

void runEventually(Runnable cmd)

Runs the command eventually, most likely on an unused thread. This is good for cleaning up memory or doing other house-keeping chores only when there isn't any other work to do. Each implementation may handle eventualies different, and no guarantee is made about what order your command is run (it could be run immediately in a parallel thread, or it could wait a few minutes until a thread-hungry process is complete, and get cleared by starving threads before they are released.

Parameters:

cmd - - A command to run whenever there is time. No guarantee is made about how soon or how later the process is run. A best-effort is made to use warm threads with nothing better to do to process eventually commands.

resolve

<T> void resolve(Future<T> future,
                 ReceivesValue<T> receiver)

Resolves a future in another thread / using a shared poller. In concurrent environments allowed many threads, resolve will dedicate a single thread to wait on the future; but in a starved environment, a single thread will be used to check for completed futures, dispatch callbacks, sleep a little, and "busy wait" on all pending futures. (this functionality is not yet implemented).

Parameters:

future - - The future to wait upon.

receiver - - The handler to receive the value. If received is an instanceof ErrorHandler, it will receive any exceptions caused by the future (after unwrapping ExecutionException and RuntimeException).

flush

boolean flush(Thread thread,
              int timeout)

Flushes all jobs for a given thread, up to a given millisecond timeout. This attempts to clear all jobs registered for the given thread, and waits a maximum of timeout milliseconds. All deferred and finally tasks will be cleared, and eventualies will be run if there is time to bother. This method blocks / busy waits until the work is complete or the timeout is exceeded.

Parameters:

thread - - The thread to finish.

timeout - - The maximum time to take. Send 0 to wait indefinitely.

Returns:

- true is all work (except eventuallies) was completed.

kill

boolean kill(Thread thread,
             int timeout)

Flushes all jobs for the given thread, and then kills it. A killed thread will not receive any new work if asks for it, so draining its task queue and denying it work will shut it down. The thread will be manually interrupted after timeout milliseconds.

Parameters:

thread - - The thread to finish and then kill.

timeout - - How many milliseconds to wait for a graceful shutdown.

Returns:

- true if the thread shutdown gracefully. Once the timeout is passed, the running thread will interrupt the given thread, and then return false.

trySleep

boolean trySleep(float millis)

Attempts to sleep, if the current thread is not interrupted. Experiments with rewriting AST in GWT may make "pseudo-sleep" possible, by travelling up the method call to the nearest method with void return type, and moving all code into a scoped callback function. Such experiments will not likely yield useful rewards, but will be carried out anyway. Until then, sleep is a no-op in GWT. When the GwtThread class is complete, calling sleep will tell the ConcurrencyService to stop running tasks from this thread until the given timeout is expired.

Parameters:

millis - - The millis to wait. Floating point converts to nanos.

Returns:

- true is wait was successful and we are not in an interrupted state.

threadStartTime

double threadStartTime(Thread currentThread)

Tells what time the current process for the current thread started. The thread itself may be much older, if it has stayed busy enough to avoid starvation.

Parameters:

currentThread - - The thread who's start time to check.

Returns:

- nanos since now() that the thread started.

now

double now()

Returns:

Current nano-time, since TimeService.birth().

newLock

AsyncLock newLock()

Returns:

A lock suitable for the environment in which you are running. We may extend the Lock interface, and require subclasses that offer a given, small set of additional functionality.