minor #7099 Clarify Process::wait() callback behaviour (Lilchef)

xabbuh · xabbuh · commit b8a2e5df3119 · 2016-11-05T11:33:24.000+01:00
This PR was submitted for the 3.1 branch but it was merged into the 2.7 branch instead (closes #7099). Discussion ---------- Clarify Process::wait() callback behaviour There was no clear description of when the Process::wait() callback was triggered and it seemed like it would be called once the process was complete which is incorrect. I lost several hours after misunderstanding how this works and then trying to figure out why my 'after process' code was being triggered before the process had finished. Hopefully this change makes it clearer. Commits ------- d696a15 Clarify Process::wait() callback behaviour
diff --git a/components/process.rst b/components/process.rst
@@ -113,7 +113,24 @@ are done doing other stuff::
     $process->start();
 
     // ... do other things
+    
+    $process->wait();
+    
+    // ... do things after the process has finished
 
+.. note::
+
+    The :method:`Symfony\\Component\\Process\\Process::wait` method is blocking,
+    which means that your code will halt at this line until the external
+    process is completed.
+
+:method:`Symfony\\Component\\Process\\Process::wait` takes one optional argument:
+a callback that is called repeatedly whilst the process is still running, passing
+in the output and its type::
+
+    $process = new Process('ls -lsa');
+    $process->start();
+    
     $process->wait(function ($type, $buffer) {
         if (Process::ERR === $type) {
             echo 'ERR > '.$buffer;
@@ -122,12 +139,6 @@ are done doing other stuff::
         }
     });
 
-.. note::
-
-    The :method:`Symfony\\Component\\Process\\Process::wait` method is blocking,
-    which means that your code will halt at this line until the external
-    process is completed.
-
 Stopping a Process
 ------------------
 
