001/*
002 * Copyright (c) 2012-2018 Institut National des Sciences Appliquées de Lyon (INSA Lyon) and others
003 *
004 * This program and the accompanying materials are made available under the
005 * terms of the Eclipse Public License 2.0 which is available at
006 * http://www.eclipse.org/legal/epl-2.0.
007 *
008 * SPDX-License-Identifier: EPL-2.0
009 */
010
011package gololang.concurrent.async;
012
013/**
014 * A future is an abstraction over the eventual result of a possibly asynchronous computation.
015 *
016 * This interface is intended to be used in conjunction with {@code Promise}. A future is a read-only view over a
017 * promise.
018 *
019 * {@code Future} objects are made composable in Golo through a set of augmentations: {@code filter}, {@code map}, etc.
020 * You should consult the "golodoc" of the {@code gololang.Async} module.
021 */
022public interface Future {
023
024  /**
025   * Non-blocking get.
026   *
027   * @return the future value, which may be {@code null} if it has not been resolved yet.
028   */
029  Object get();
030
031  /**
032   * Blocking get, waiting until the future has been resolved.
033   *
034   * @return the future value.
035   * @throws InterruptedException when the current thread is being interrupted.
036   */
037  Object blockingGet() throws InterruptedException;
038
039  /**
040   * Test whether the future has been resolved, that is, the future is either set or failed.
041   *
042   * @return {@code true} if the future is resolved, {@code false} otherwise.
043   */
044  boolean isResolved();
045
046  /**
047   * Test whether the future has failed.
048   *
049   * @return {@code true} if the future is resolved and failed, {@code false} otherwise.
050   */
051  boolean isFailed();
052
053  /**
054   * Registers a callback for when the future is set. If the future has already been set, then it is executed
055   * immediately from the caller thread.
056   *
057   * @param observer the callback.
058   * @return this future object.
059   */
060  Future onSet(Observer observer);
061
062  /**
063   * Registers a callback for when the future fails. If the future has already been failed, then it is executed
064   * immediately from the caller thread.
065   *
066   * @param observer the callback.
067   * @return this future object.
068   */
069  Future onFail(Observer observer);
070
071  /**
072   * Simple interface for a future observer / callback.
073   */
074  @FunctionalInterface
075  interface Observer {
076
077    /**
078     * Callback method.
079     *
080     * @param value the future value.
081     */
082    void apply(Object value);
083  }
084}