From 636498930ad831e75aa3ef6c39e73cd33ccabb65 Mon Sep 17 00:00:00 2001
From: Romain Neutron <imprec@gmail.com>
Date: Sun, 14 Apr 2013 18:02:38 +0200
Subject: [PATCH] [Process] Add documentation about `signal` and `getPid`
 methods

---
 components/process.rst | 95 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 88 insertions(+), 7 deletions(-)

diff --git a/components/process.rst b/components/process.rst
index 894172701ca..658c1d48e7d 100644
--- a/components/process.rst
+++ b/components/process.rst
@@ -60,12 +60,12 @@ anonymous function to the
             echo 'OUT > '.$buffer;
         }
     });
-    
+
 .. versionadded:: 2.1
     The non-blocking feature was added in 2.1.
-    
+
 You can also start the subprocess and then let it run asynchronously, retrieving
-output and the status in your main process whenever you need it. Use the 
+output and the status in your main process whenever you need it. Use the
 :method:`Symfony\\Component\\Process\\Process::start` method to start an asynchronous
 process, the :method:`Symfony\\Component\\Process\\Process::isRunning` method
 to check if the process is done and the
@@ -73,21 +73,21 @@ to check if the process is done and the
 
     $process = new Process('ls -lsa');
     $process->start();
-    
+
     while ($process->isRunning()) {
         // waiting for process to finish
     }
 
     echo $process->getOutput();
-    
+
 You can also wait for a process to end if you started it asynchronously and
 are done doing other stuff::
 
     $process = new Process('ls -lsa');
     $process->start();
-    
+
     // do other things
-    
+
     $process->wait(function ($type, $buffer) {
         if ('err' === $type) {
             echo 'ERR > '.$buffer;
@@ -96,6 +96,30 @@ are done doing other stuff::
         }
     });
 
+.. note::
+
+    Please consider that the :method:`Symfony\\Component\\Process\\Process::wait`
+    method is blocking.
+
+.. versionadded:: 2.3
+    The ``signal`` parameter of the ``stop`` method was added in Symfony 2.3.
+
+Any asynchronous process can be stopped at any time with the
+:method:`Symfony\\Component\\Process\\Process::stop` method. This method takes
+two arguments : a timeout and a signal. Once the timeout is reached, the signal
+is sent to the running process.
+The default signal sent to a process is ``SIGKILL``. Please read the signal
+documentation below to know more about signal handling in the Process component.
+
+.. code-block:: php
+
+    $process = new Process('ls -lsa');
+    $process->start();
+
+    // ... do other things
+
+    $process->stop(3, SIGINT);
+
 If you want to execute some PHP code in isolation, use the ``PhpProcess``
 instead::
 
@@ -148,4 +172,61 @@ check regularly::
         usleep(200000);
     }
 
+Process Signals
+---------------
+
+.. versionadded:: 2.3
+    The ``signal`` method was added in Symfony 2.3.
+
+When running programs asynchronously, you can send it posix signals with the
+:method:`Symfony\\Component\\Process\\Process::signal` method.
+
+.. code-block:: php
+
+    use Symfony\Component\Process\Process;
+
+    $process = new Process('find / -name "rabbit"');
+    $process->start();
+
+    // will send a SIGKILL to the process
+    $process->signal(SIGKILL);
+
+.. caution::
+
+    Due to some limitations in PHP, if you're using signals with the Process
+    component, you may have to prefix your commands with `exec`_. Please read
+    `Symfony Issue#5769`_ and `PHP Bug#39992`_ to understand why this is happening.
+
+    POSIX signals are not available on Windows platforms, please refer to the
+    `PHP documentation`_ for available signals.
+
+Process Pid
+-----------
+
+.. versionadded:: 2.3
+    The ``getPid`` method was added in Symfony 2.3.
+
+You can access the `pid`_ of a running process with the
+:method:`Symfony\\Component\\Process\\Process::getPid` method.
+
+.. code-block:: php
+
+    use Symfony\Component\Process\Process;
+
+    $process = new Process('/usr/bin/php worker.php');
+    $process->start();
+
+    $pid = $process->getPid();
+
+.. caution::
+
+    Due to some limitations in PHP, if you want to get the pid of a symfony Process,
+    you may have to prefix your commands with `exec`_. Please read
+    `Symfony Issue#5769`_ to understand why this is happening.
+
+.. _Symfony Issue#5759: https://github.com/symfony/symfony/issues/5759
+.. _PHP Bug#39992: https://bugs.php.net/bug.php?id=39992
+.. _exec: http://en.wikipedia.org/wiki/Exec_(operating_system)
+.. _pid: http://en.wikipedia.org/wiki/Process_identifier
+.. _PHP Documentation: http://php.net/manual/en/pcntl.constants.php
 .. _Packagist: https://packagist.org/packages/symfony/process