Req #69321 [Opn]: Please clarify when users should design functions for pass-by-reference

Edit report at https://bugs.php.net/bug.php?id=69321&edit=1 ID: 69321 Updated by: cmb@php.net Reported by: php at richardneill dot org Summary: Please clarify when users should design functions for pass-by-reference Status: Open Type: Feature/Change Request Package: Documentation problem PHP Version: Irrelevant Block user comment: N Private report: N New Comment: See <http://schlueters.de/blog/archives/125-do-not-use-php-references.html>. Previous Comments: ------------------------------------------------------------------------ [2015-03-28 19:33:29] php at richardneill dot org Description: ------------ I think it would be worth clarifying when it is necessary to use pass-by-reference vs pass-by-value. The script below shows that: PHP already optimises pass-by-value function calls to do zero-copy (or copy-on-write) regardless of whether the function definition contains a by-reference instruction. Also, it would be helpful to explain why call-time-pass-by-reference is not allowed [I can see cases where a function that works normally by-value could sometimes be called by-reference.] Lastly, why can't we have the "&" in the function call, even if it is mere syntactic sugar? It's otherwise a source of code-unreadability. Test script: --------------- #!/usr/bin/php <?php function sum($array,$max){ //For Reference, use: "&$array" $sum=0; for ($i=0; $i<2; $i++){ #$array[$i]++; //Uncomment this line to modify the array within the function. $sum += $array[$i]; } return ($sum); } $max = 1E7 //10 M data points. $data = range(0,$max,1); $start = microtime(true); for ($x = 0 ; $x < 100; $x++){ $sum = sum($data, $max); } $end = microtime(true); echo "Time: ".($end - $start)." s\n"; ?> Actual result: -------------- Measured Run times: # PASS BY MODIFIED? Time - ------- --------- ---- 1 value no 56 us 2 reference no 58 us 3 valuue yes 129 s 4 reference yes 66 us Conclusions: 1. PHP is already smart about zero-copy / copy-on-write. A function call does NOT copy the data unless it needs to; the data is only copied on write. That's why #1 and #2 take similar times, whereas #3 takes 2 million times longer than #4. [You never need to use &$array to ask the compiler to do a zero-copy optimisation; it can work that out for itself.] 2. You do use &$array to tell the compiler "it is OK for the function to over-write my argument in place, I don't need the original any more." This can make a huge difference to performance when we have large amounts of memory to copy. (This is the only way it is done in C, arrays are always passed as pointers) 3. The other use of & is as a way to specify where data should be *returned*. (eg as used by exec() ). (This is a C-like way of passing pointers for outputs, whereas PHP functions normally return complex types, or multiple answers in an array) 4. It's unhelpful that only the function definition has &. The caller should have it, at least as syntactic sugar. Otherwise it leads to unreadable code: because the person reading the function call doesn't expect it to pass by reference. At the moment, it's necessary to write a function call with a comment, thus: $sum = sum($data,$max); //warning, $data passed by reference, and may be modified. 5. Sometimes, pass by reference could be at the choice of the caller, NOT the function definition. PHP doesn't allow it, but it would be meaningful for the caller to decide to pass data in as a reference. i.e. "I'm done with the variable, it's OK to stomp on it in memory". ------------------------------------------------------------------------ -- Edit this bug report at https://bugs.php.net/bug.php?id=69321&edit=1