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