sample/java.util.concurrent.Future.txt

   1 *java.util.concurrent.Future* *Future* A Future represents the result of an asyn
   2
   3 public interface interface Future<V>
   4
   5
   6 |java.util.concurrent.Future_Description|
   7 |java.util.concurrent.Future_Fields|
   8 |java.util.concurrent.Future_Constructors|
   9 |java.util.concurrent.Future_Methods|
  10
  11 ================================================================================
  12
  13 *java.util.concurrent.Future_Methods*
  14 |java.util.concurrent.Future.cancel(boolean)|Attempts to cancel execution of th
  15 |java.util.concurrent.Future.get()|Waits if necessary for the computation to co
  16 |java.util.concurrent.Future.get(long,TimeUnit)|Waits if necessary for at most
  17 |java.util.concurrent.Future.isCancelled()|Returns true if this task was cancel
  18 |java.util.concurrent.Future.isDone()|Returns true if this task completed.
  19
  20 *java.util.concurrent.Future_Description*
  21
  22 A Future represents the result of an asynchronous computation. Methods are
  23 provided to check if the computation is complete, to wait for its completion,
  24 and to retrieve the result of the computation. The result can only be retrieved
  25 using method get when the computation has completed, blocking if necessary
  26 until it is ready. Cancellation is performed by the cancel method. Additional
  27 methods are provided to determine if the task completed normally or was
  28 cancelled. Once a computation has completed, the computation cannot be
  29 cancelled. If you would like to use a Future for the sake of cancellability but
  30 not provide a usable result, you can declare types of the form Future<?> and
  31 return null as a result of the underlying task.
  32
  33 Sample Usage (Note that the following classes are all made-up.)
  34
  35 interface ArchiveSearcher { String search(String target); } class App {
  36 ExecutorService executor = ... ArchiveSearcher searcher = ... void
  37 showSearch(final String target) throws InterruptedException { Future<String>
  38 future = executor.submit(new Callable<String>() { public String call() { return
  39 searcher.search(target); }}); displayOtherThings(); // do other things while
  40 searching try { displayText(future.get()); // use future } catch
  41 (ExecutionException ex) { cleanup(); return; } } }
  42
  43 The (|java.util.concurrent.FutureTask|) class is an implementation of Future
  44 that implements Runnable, and so may be executed by an Executor. For example,
  45 the above construction with submit could be replaced by:
  46
  47 FutureTask<String> future = new FutureTask<String>(new Callable<String>() {
  48 public String call() { return searcher.search(target); }});
  49 executor.execute(future);
  50
  51 Memory consistency effects: Actions taken by the asynchronous computation
  52 happen-before actions following the correspondingFuture.get()in another thread.
  53
  54
  55
  56 *java.util.concurrent.Future.cancel(boolean)*
  57
  58 public boolean cancel(boolean mayInterruptIfRunning)
  59
  60 Attempts to cancel execution of this task. This attempt will fail if the task
  61 has already completed, has already been cancelled, or could not be cancelled
  62 for some other reason. If successful, and this task has not started when cancel
  63 is called, this task should never run. If the task has already started, then
  64 the mayInterruptIfRunning parameter determines whether the thread executing
  65 this task should be interrupted in an attempt to stop the task.
  66
  67 After this method returns, subsequent calls to (|java.util.concurrent.Future|)
  68 will always return true. Subsequent calls to (|java.util.concurrent.Future|)
  69 will always return true if this method returned true.
  70
  71
  72     mayInterruptIfRunning - true if the thread executing this task should be interrupted; otherwise,
  73        in-progress tasks are allowed to complete
  74
  75     Returns: false if the task could not be cancelled, typically because it has already
  76              completed normally; true otherwise
  77
  78 *java.util.concurrent.Future.get()*
  79
  80 public |V| get()
  81   throws |java.util.concurrent.ExecutionException|
  82          |java.lang.InterruptedException|
  83
  84 Waits if necessary for the computation to complete, and then retrieves its
  85 result.
  86
  87
  88
  89     Returns: the computed result
  90
  91 *java.util.concurrent.Future.get(long,TimeUnit)*
  92
  93 public |V| get(
  94   long timeout,
  95   java.util.concurrent.TimeUnit unit)
  96   throws |java.util.concurrent.ExecutionException|
  97          |java.lang.InterruptedException|
  98          |java.util.concurrent.TimeoutException|
  99
 100 Waits if necessary for at most the given time for the computation to complete,
 101 and then retrieves its result, if available.
 102
 103
 104     timeout - the maximum time to wait
 105     unit - the time unit of the timeout argument
 106
 107     Returns: the computed result
 108
 109 *java.util.concurrent.Future.isCancelled()*
 110
 111 public boolean isCancelled()
 112
 113 Returns true if this task was cancelled before it completed normally.
 114
 115
 116
 117     Returns: true if this task was cancelled before it completed
 118
 119 *java.util.concurrent.Future.isDone()*
 120
 121 public boolean isDone()
 122
 123 Returns true if this task completed.
 124
 125 Completion may be due to normal termination, an exception, or cancellation --
 126 in all of these cases, this method will return true.
 127
 128
 129
 130     Returns: true if this task completed
 131
 132