rev 54134 : [mq]: 8220684-Process-waitFor-long-TimeUnit-can-return-false-for-a-process-that-exited-within-the-timeout

   1 /*
   2  * Copyright (c) 1995, 2019, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.lang;
  27 
  28 import java.io.*;
  29 import java.lang.ProcessBuilder.Redirect;
  30 import java.util.concurrent.CompletableFuture;
  31 import java.util.concurrent.ForkJoinPool;
  32 import java.util.concurrent.TimeUnit;
  33 import java.util.stream.Stream;
  34 
  35 /**
  36  * {@code Process} provides control of native processes started by
  37  * ProcessBuilder.start and Runtime.exec.
  38  * The class provides methods for performing input from the process, performing
  39  * output to the process, waiting for the process to complete,
  40  * checking the exit status of the process, and destroying (killing)
  41  * the process.
  42  * The {@link ProcessBuilder#start()} and
  43  * {@link Runtime#exec(String[],String[],File) Runtime.exec}
  44  * methods create a native process and return an instance of a
  45  * subclass of {@code Process} that can be used to control the process
  46  * and obtain information about it.
  47  *
  48  * <p>The methods that create processes may not work well for special
  49  * processes on certain native platforms, such as native windowing
  50  * processes, daemon processes, Win16/DOS processes on Microsoft
  51  * Windows, or shell scripts.
  52  *
  53  * <p>By default, the created process does not have its own terminal
  54  * or console.  All its standard I/O (i.e. stdin, stdout, stderr)
  55  * operations will be redirected to the parent process, where they can
  56  * be accessed via the streams obtained using the methods
  57  * {@link #getOutputStream()},
  58  * {@link #getInputStream()}, and
  59  * {@link #getErrorStream()}.
  60  * The parent process uses these streams to feed input to and get output
  61  * from the process.  Because some native platforms only provide
  62  * limited buffer size for standard input and output streams, failure
  63  * to promptly write the input stream or read the output stream of
  64  * the process may cause the process to block, or even deadlock.
  65  *
  66  * <p>Where desired, <a href="ProcessBuilder.html#redirect-input">
  67  * process I/O can also be redirected</a>
  68  * using methods of the {@link ProcessBuilder} class.
  69  *
  70  * <p>The process is not killed when there are no more references to
  71  * the {@code Process} object, but rather the process
  72  * continues executing asynchronously.
  73  *
  74  * <p>There is no requirement that the process represented by a {@code
  75  * Process} object execute asynchronously or concurrently with respect
  76  * to the Java process that owns the {@code Process} object.
  77  *
  78  * <p>As of 1.5, {@link ProcessBuilder#start()} is the preferred way
  79  * to create a {@code Process}.
  80  *
  81  * <p>Subclasses of Process should override the {@link #onExit()} and
  82  * {@link #toHandle()} methods to provide a fully functional Process including the
  83  * {@linkplain #pid() process id},
  84  * {@linkplain #info() information about the process},
  85  * {@linkplain #children() direct children}, and
  86  * {@linkplain #descendants() direct children plus descendants of those children} of the process.
  87  * Delegating to the underlying Process or ProcessHandle is typically
  88  * easiest and most efficient.
  89  *
  90  * @since   1.0
  91  */
  92 public abstract class Process {
  93     /**
  94      * Default constructor for Process.
  95      */
  96     public Process() {}
  97 
  98     /**
  99      * Returns the output stream connected to the normal input of the
 100      * process.  Output to the stream is piped into the standard
 101      * input of the process represented by this {@code Process} object.
 102      *
 103      * <p>If the standard input of the process has been redirected using
 104      * {@link ProcessBuilder#redirectInput(Redirect)
 105      * ProcessBuilder.redirectInput}
 106      * then this method will return a
 107      * <a href="ProcessBuilder.html#redirect-input">null output stream</a>.
 108      *
 109      * <p>Implementation note: It is a good idea for the returned
 110      * output stream to be buffered.
 111      *
 112      * @return the output stream connected to the normal input of the
 113      *         process
 114      */
 115     public abstract OutputStream getOutputStream();
 116 
 117     /**
 118      * Returns the input stream connected to the normal output of the
 119      * process.  The stream obtains data piped from the standard
 120      * output of the process represented by this {@code Process} object.
 121      *
 122      * <p>If the standard output of the process has been redirected using
 123      * {@link ProcessBuilder#redirectOutput(Redirect)
 124      * ProcessBuilder.redirectOutput}
 125      * then this method will return a
 126      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 127      *
 128      * <p>Otherwise, if the standard error of the process has been
 129      * redirected using
 130      * {@link ProcessBuilder#redirectErrorStream(boolean)
 131      * ProcessBuilder.redirectErrorStream}
 132      * then the input stream returned by this method will receive the
 133      * merged standard output and the standard error of the process.
 134      *
 135      * <p>Implementation note: It is a good idea for the returned
 136      * input stream to be buffered.
 137      *
 138      * @return the input stream connected to the normal output of the
 139      *         process
 140      */
 141     public abstract InputStream getInputStream();
 142 
 143     /**
 144      * Returns the input stream connected to the error output of the
 145      * process.  The stream obtains data piped from the error output
 146      * of the process represented by this {@code Process} object.
 147      *
 148      * <p>If the standard error of the process has been redirected using
 149      * {@link ProcessBuilder#redirectError(Redirect)
 150      * ProcessBuilder.redirectError} or
 151      * {@link ProcessBuilder#redirectErrorStream(boolean)
 152      * ProcessBuilder.redirectErrorStream}
 153      * then this method will return a
 154      * <a href="ProcessBuilder.html#redirect-output">null input stream</a>.
 155      *
 156      * <p>Implementation note: It is a good idea for the returned
 157      * input stream to be buffered.
 158      *
 159      * @return the input stream connected to the error output of
 160      *         the process
 161      */
 162     public abstract InputStream getErrorStream();
 163 
 164     /**
 165      * Causes the current thread to wait, if necessary, until the
 166      * process represented by this {@code Process} object has
 167      * terminated.  This method returns immediately if the process
 168      * has already terminated.  If the process has not yet
 169      * terminated, the calling thread will be blocked until the
 170      * process exits.
 171      *
 172      * @return the exit value of the process represented by this
 173      *         {@code Process} object.  By convention, the value
 174      *         {@code 0} indicates normal termination.
 175      * @throws InterruptedException if the current thread is
 176      *         {@linkplain Thread#interrupt() interrupted} by another
 177      *         thread while it is waiting, then the wait is ended and
 178      *         an {@link InterruptedException} is thrown.
 179      */
 180     public abstract int waitFor() throws InterruptedException;
 181 
 182     /**
 183      * Causes the current thread to wait, if necessary, until the
 184      * process represented by this {@code Process} object has
 185      * terminated, or the specified waiting time elapses.
 186      *
 187      * <p>If the process has already terminated then this method returns
 188      * immediately with the value {@code true}.  If the process has not
 189      * terminated and the timeout value is less than, or equal to, zero, then
 190      * this method returns immediately with the value {@code false}.
 191      *
 192      * <p>The default implementation of this methods polls the {@code exitValue}
 193      * to check if the process has terminated. Concrete implementations of this
 194      * class are strongly encouraged to override this method with a more
 195      * efficient implementation.
 196      *
 197      * @param timeout the maximum time to wait
 198      * @param unit the time unit of the {@code timeout} argument
 199      * @return {@code true} if the process has exited and {@code false} if
 200      *         the waiting time elapsed before the process has exited.
 201      * @throws InterruptedException if the current thread is interrupted
 202      *         while waiting.
 203      * @throws NullPointerException if unit is null
 204      * @since 1.8
 205      */
 206     public boolean waitFor(long timeout, TimeUnit unit)
 207         throws InterruptedException
 208     {
 209         long remainingNanos = unit.toNanos(timeout);    // throw NPE before other conditions
 210         if (hasExited()) return true;
 211         if (timeout <= 0) return false;
 212 
 213         long deadline = System.nanoTime() + remainingNanos;
 214         do {
 215             Thread.sleep(Math.min(TimeUnit.NANOSECONDS.toMillis(remainingNanos) + 1, 100));
 216             if (hasExited()) return true;
 217             remainingNanos = deadline - System.nanoTime();
 218         } while (remainingNanos > 0);






 219         return false;
 220     }
 221 
 222     /**
 223      * Returns the exit value for the process.
 224      *
 225      * @return the exit value of the process represented by this
 226      *         {@code Process} object.  By convention, the value
 227      *         {@code 0} indicates normal termination.
 228      * @throws IllegalThreadStateException if the process represented
 229      *         by this {@code Process} object has not yet terminated
 230      */
 231     public abstract int exitValue();
 232 
 233     /**
 234      * Kills the process.
 235      * Whether the process represented by this {@code Process} object is
 236      * {@linkplain #supportsNormalTermination normally terminated} or not is
 237      * implementation dependent.
 238      * Forcible process destruction is defined as the immediate termination of a
 239      * process, whereas normal termination allows the process to shut down cleanly.
 240      * If the process is not alive, no action is taken.
 241      * <p>
 242      * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is
 243      * {@linkplain java.util.concurrent.CompletableFuture#complete completed}
 244      * when the process has terminated.
 245      */
 246     public abstract void destroy();
 247 
 248     /**
 249      * Kills the process forcibly. The process represented by this
 250      * {@code Process} object is forcibly terminated.
 251      * Forcible process destruction is defined as the immediate termination of a
 252      * process, whereas normal termination allows the process to shut down cleanly.
 253      * If the process is not alive, no action is taken.
 254      * <p>
 255      * The {@link java.util.concurrent.CompletableFuture} from {@link #onExit} is
 256      * {@linkplain java.util.concurrent.CompletableFuture#complete completed}
 257      * when the process has terminated.
 258      * <p>
 259      * Invoking this method on {@code Process} objects returned by
 260      * {@link ProcessBuilder#start} and {@link Runtime#exec} forcibly terminate
 261      * the process.
 262      *
 263      * @implSpec
 264      * The default implementation of this method invokes {@link #destroy}
 265      * and so may not forcibly terminate the process.
 266      * @implNote
 267      * Concrete implementations of this class are strongly encouraged to override
 268      * this method with a compliant implementation.
 269      * @apiNote
 270      * The process may not terminate immediately.
 271      * i.e. {@code isAlive()} may return true for a brief period
 272      * after {@code destroyForcibly()} is called. This method
 273      * may be chained to {@code waitFor()} if needed.
 274      *
 275      * @return the {@code Process} object representing the
 276      *         process forcibly destroyed
 277      * @since 1.8
 278      */
 279     public Process destroyForcibly() {
 280         destroy();
 281         return this;
 282     }
 283 
 284     /**
 285      * Returns {@code true} if the implementation of {@link #destroy} is to
 286      * normally terminate the process,
 287      * Returns {@code false} if the implementation of {@code destroy}
 288      * forcibly and immediately terminates the process.
 289      * <p>
 290      * Invoking this method on {@code Process} objects returned by
 291      * {@link ProcessBuilder#start} and {@link Runtime#exec} return
 292      * {@code true} or {@code false} depending on the platform implementation.
 293      *
 294      * @implSpec
 295      * This implementation throws an instance of
 296      * {@link java.lang.UnsupportedOperationException} and performs no other action.
 297      *
 298      * @return {@code true} if the implementation of {@link #destroy} is to
 299      *         normally terminate the process;
 300      *         otherwise, {@link #destroy} forcibly terminates the process
 301      * @throws UnsupportedOperationException if the Process implementation
 302      *         does not support this operation
 303      * @since 9
 304      */
 305     public boolean supportsNormalTermination() {
 306         throw new UnsupportedOperationException(this.getClass()
 307                 + ".supportsNormalTermination() not supported" );
 308     }
 309 
 310     /**
 311      * Tests whether the process represented by this {@code Process} is
 312      * alive.
 313      *
 314      * @return {@code true} if the process represented by this
 315      *         {@code Process} object has not yet terminated.
 316      * @since 1.8
 317      */
 318     public boolean isAlive() {
 319         return !hasExited();
 320     }
 321 
 322     /**
 323      * This is called from the default implementation of
 324      * {@code waitFor(long, TimeUnit)}, which is specified to poll
 325      * {@code exitValue()}.
 326      */
 327     private boolean hasExited() {
 328         try {
 329             exitValue();


 330             return true;
 331         } catch (IllegalThreadStateException e) {
 332             return false;
 333         }
 334     }
 335 
 336     /**
 337      * Returns the native process ID of the process.
 338      * The native process ID is an identification number that the operating
 339      * system assigns to the process.
 340      *
 341      * @implSpec
 342      * The implementation of this method returns the process id as:
 343      * {@link #toHandle toHandle().pid()}.
 344      *
 345      * @return the native process id of the process
 346      * @throws UnsupportedOperationException if the Process implementation
 347      *         does not support this operation
 348      * @since 9
 349      */
 350     public long pid() {
 351         return toHandle().pid();
 352     }
 353 
 354     /**
 355      * Returns a {@code CompletableFuture<Process>} for the termination of the Process.
 356      * The {@link java.util.concurrent.CompletableFuture} provides the ability
 357      * to trigger dependent functions or actions that may be run synchronously
 358      * or asynchronously upon process termination.
 359      * When the process has terminated the CompletableFuture is
 360      * {@link java.util.concurrent.CompletableFuture#complete completed} regardless
 361      * of the exit status of the process.
 362      * <p>
 363      * Calling {@code onExit().get()} waits for the process to terminate and returns
 364      * the Process. The future can be used to check if the process is
 365      * {@linkplain java.util.concurrent.CompletableFuture#isDone done} or to
 366      * {@linkplain java.util.concurrent.CompletableFuture#get() wait} for it to terminate.
 367      * {@linkplain java.util.concurrent.CompletableFuture#cancel(boolean) Cancelling}
 368      * the CompletableFuture does not affect the Process.
 369      * <p>
 370      * Processes returned from {@link ProcessBuilder#start} override the
 371      * default implementation to provide an efficient mechanism to wait
 372      * for process exit.
 373      *
 374      * @apiNote
 375      * Using {@link #onExit() onExit} is an alternative to
 376      * {@link #waitFor() waitFor} that enables both additional concurrency
 377      * and convenient access to the result of the Process.
 378      * Lambda expressions can be used to evaluate the result of the Process
 379      * execution.
 380      * If there is other processing to be done before the value is used
 381      * then {@linkplain #onExit onExit} is a convenient mechanism to
 382      * free the current thread and block only if and when the value is needed.
 383      * <br>
 384      * For example, launching a process to compare two files and get a boolean if they are identical:
 385      * <pre> {@code   Process p = new ProcessBuilder("cmp", "f1", "f2").start();
 386      *    Future<Boolean> identical = p.onExit().thenApply(p1 -> p1.exitValue() == 0);
 387      *    ...
 388      *    if (identical.get()) { ... }
 389      * }</pre>
 390      *
 391      * @implSpec
 392      * This implementation executes {@link #waitFor()} in a separate thread
 393      * repeatedly until it returns successfully. If the execution of
 394      * {@code waitFor} is interrupted, the thread's interrupt status is preserved.
 395      * <p>
 396      * When {@link #waitFor()} returns successfully the CompletableFuture is
 397      * {@linkplain java.util.concurrent.CompletableFuture#complete completed} regardless
 398      * of the exit status of the process.
 399      *
 400      * This implementation may consume a lot of memory for thread stacks if a
 401      * large number of processes are waited for concurrently.
 402      * <p>
 403      * External implementations should override this method and provide
 404      * a more efficient implementation. For example, to delegate to the underlying
 405      * process, it can do the following:
 406      * <pre>{@code
 407      *    public CompletableFuture<Process> onExit() {
 408      *       return delegate.onExit().thenApply(p -> this);
 409      *    }
 410      * }</pre>
 411      * @apiNote
 412      * The process may be observed to have terminated with {@link #isAlive}
 413      * before the ComputableFuture is completed and dependent actions are invoked.
 414      *
 415      * @return a new {@code CompletableFuture<Process>} for the Process
 416      *
 417      * @since 9
 418      */
 419     public CompletableFuture<Process> onExit() {
 420         return CompletableFuture.supplyAsync(this::waitForInternal);
 421     }
 422 
 423     /**
 424      * Wait for the process to exit by calling {@code waitFor}.
 425      * If the thread is interrupted, remember the interrupted state to
 426      * be restored before returning. Use ForkJoinPool.ManagedBlocker
 427      * so that the number of workers in case ForkJoinPool is used is
 428      * compensated when the thread blocks in waitFor().
 429      *
 430      * @return the Process
 431      */
 432     private Process waitForInternal() {
 433         boolean interrupted = false;
 434         while (true) {
 435             try {
 436                 ForkJoinPool.managedBlock(new ForkJoinPool.ManagedBlocker() {
 437                     @Override
 438                     public boolean block() throws InterruptedException {
 439                         waitFor();
 440                         return true;
 441                     }
 442 
 443                     @Override
 444                     public boolean isReleasable() {
 445                         return !isAlive();
 446                     }
 447                 });
 448                 break;
 449             } catch (InterruptedException x) {
 450                 interrupted = true;
 451             }
 452         }
 453         if (interrupted) {
 454             Thread.currentThread().interrupt();
 455         }
 456         return this;
 457     }
 458 
 459     /**
 460      * Returns a ProcessHandle for the Process.
 461      *
 462      * {@code Process} objects returned by {@link ProcessBuilder#start} and
 463      * {@link Runtime#exec} implement {@code toHandle} as the equivalent of
 464      * {@link ProcessHandle#of(long) ProcessHandle.of(pid)} including the
 465      * check for a SecurityManager and {@code RuntimePermission("manageProcess")}.
 466      *
 467      * @implSpec
 468      * This implementation throws an instance of
 469      * {@link java.lang.UnsupportedOperationException} and performs no other action.
 470      * Subclasses should override this method to provide a ProcessHandle for the
 471      * process.  The methods {@link #pid}, {@link #info}, {@link #children},
 472      * and {@link #descendants}, unless overridden, operate on the ProcessHandle.
 473      *
 474      * @return Returns a ProcessHandle for the Process
 475      * @throws UnsupportedOperationException if the Process implementation
 476      *         does not support this operation
 477      * @throws SecurityException if a security manager has been installed and
 478      *         it denies RuntimePermission("manageProcess")
 479      * @since 9
 480      */
 481     public ProcessHandle toHandle() {
 482         throw new UnsupportedOperationException(this.getClass()
 483                 + ".toHandle() not supported");
 484     }
 485 
 486     /**
 487      * Returns a snapshot of information about the process.
 488      *
 489      * <p> A {@link ProcessHandle.Info} instance has accessor methods
 490      * that return information about the process if it is available.
 491      *
 492      * @implSpec
 493      * This implementation returns information about the process as:
 494      * {@link #toHandle toHandle().info()}.
 495      *
 496      * @return a snapshot of information about the process, always non-null
 497      * @throws UnsupportedOperationException if the Process implementation
 498      *         does not support this operation
 499      * @since 9
 500      */
 501     public ProcessHandle.Info info() {
 502         return toHandle().info();
 503     }
 504 
 505     /**
 506      * Returns a snapshot of the direct children of the process.
 507      * The parent of a direct child process is the process.
 508      * Typically, a process that is {@linkplain #isAlive not alive} has no children.
 509      * <p>
 510      * <em>Note that processes are created and terminate asynchronously.
 511      * There is no guarantee that a process is {@linkplain #isAlive alive}.
 512      * </em>
 513      *
 514      * @implSpec
 515      * This implementation returns the direct children as:
 516      * {@link #toHandle toHandle().children()}.
 517      *
 518      * @return a sequential Stream of ProcessHandles for processes that are
 519      *         direct children of the process
 520      * @throws UnsupportedOperationException if the Process implementation
 521      *         does not support this operation
 522      * @throws SecurityException if a security manager has been installed and
 523      *         it denies RuntimePermission("manageProcess")
 524      * @since 9
 525      */
 526     public Stream<ProcessHandle> children() {
 527         return toHandle().children();
 528     }
 529 
 530     /**
 531      * Returns a snapshot of the descendants of the process.
 532      * The descendants of a process are the children of the process
 533      * plus the descendants of those children, recursively.
 534      * Typically, a process that is {@linkplain #isAlive not alive} has no children.
 535      * <p>
 536      * <em>Note that processes are created and terminate asynchronously.
 537      * There is no guarantee that a process is {@linkplain #isAlive alive}.
 538      * </em>
 539      *
 540      * @implSpec
 541      * This implementation returns all children as:
 542      * {@link #toHandle toHandle().descendants()}.
 543      *
 544      * @return a sequential Stream of ProcessHandles for processes that
 545      *         are descendants of the process
 546      * @throws UnsupportedOperationException if the Process implementation
 547      *         does not support this operation
 548      * @throws SecurityException if a security manager has been installed and
 549      *         it denies RuntimePermission("manageProcess")
 550      * @since 9
 551      */
 552     public Stream<ProcessHandle> descendants() {
 553         return toHandle().descendants();
 554     }
 555 
 556     /**
 557      * An input stream for a subprocess pipe that skips by reading bytes
 558      * instead of seeking, the underlying pipe does not support seek.
 559      */
 560     static class PipeInputStream extends FileInputStream {
 561 
 562         PipeInputStream(FileDescriptor fd) {
 563             super(fd);
 564         }
 565 
 566         @Override
 567         public long skip(long n) throws IOException {
 568             long remaining = n;
 569             int nr;
 570 
 571             if (n <= 0) {
 572                 return 0;
 573             }
 574 
 575             int size = (int)Math.min(2048, remaining);
 576             byte[] skipBuffer = new byte[size];
 577             while (remaining > 0) {
 578                 nr = read(skipBuffer, 0, (int)Math.min(size, remaining));
 579                 if (nr < 0) {
 580                     break;
 581                 }
 582                 remaining -= nr;
 583             }
 584 
 585             return n - remaining;
 586         }
 587     }
 588 }
--- EOF ---