javascalautils.concurrent.package-info Maven / Gradle / Ivy
/**
* Copyright 2015 Peter Nerg
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
* except in compliance with the License. You may obtain a copy of the License at
*
*
http://www.apache.org/licenses/LICENSE-2.0
*
*
Unless required by applicable law or agreed to in writing, software distributed under the
* License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
* express or implied. See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Contains utilities for concurrent/asynchronous programming.
* The core principle is the {@link javascalautils.concurrent.Promise}/{@link
* javascalautils.concurrent.Future} pattern which is the way to separate the execution/job side
* ({@link javascalautils.concurrent.Promise}) from the client/receiver side ({@link
* javascalautils.concurrent.Future}).
*
*
Promise/Future
*
* In an essence the {@link javascalautils.concurrent.Promise} is the promise to deliver a value at
* some time in the future.
* This is the handle the actual computation side of of the job uses.
*
* The {@link javascalautils.concurrent.Future} is the bearer of a value-to-be, an execution yet to
* be finished.
* The purpose is to have a placeholder for a value from an asynchronous computation.
* The preferred way to get hold of the value-to-be is to register a listener on any of the provided
* listener types since this allows for asynchronous non-blocking operations.
* The following image outlines an example of using a {@link
* javascalautils.concurrent.Promise}/{@link javascalautils.concurrent.Future} pair.
*
* 
*
*
* Executing a function
*
* In addition to manually using the {@link javascalautils.concurrent.Executor} class for performing
* asynchronous computations one can let the {@link javascalautils.concurrent.Future} class deal
* with that automatically.
* This is done by using {@link
* javascalautils.concurrent.Future#apply(javascalautils.ThrowableFunction0) Future.apply} or
* statically importing the {@link
* javascalautils.concurrent.FutureCompanion#Future(javascalautils.ThrowableFunction0)
* FutureCompanion.Future} method from the companion class to the {@link
* javascalautils.concurrent.Future}.
*
*
*
*
* import static javascalautils.concurrent.FutureCompanion.Future;
*
* Future<Integer> resultSuccess = Future(() -> 9 / 3); // The Future will at some point contain: Success(3)
* Future<Integer> resultFailure = Future(() -> 9 / 0); // The Future will at some point contain: Failure(ArithmeticException)
*
*
*
*
* The execution path for the above example is illustrated in the picture below.
*
* 
*
* Refer to the Javadoc for the classes or the Wiki for more details and examples:
* https://github.com/pnerg/java-scala-util
*
*
* @author Peter Nerg
*/
package javascalautils.concurrent;