rfc:dbc2

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
Next revisionBoth sides next revision
rfc:dbc2 [2015/02/09 22:23] – created yohgakirfc:dbc2 [2015/02/10 12:30] – krakjoe
Line 2: Line 2:
   * Version: 0.1   * Version: 0.1
   * Date: 2015-02-10   * Date: 2015-02-10
-  * Author: Yasuo Ohgaki <yohgaki@ohgaki.net>+  * Author: Yasuo Ohgaki <yohgaki@ohgaki.net>, Dmitry Stogov <dmitry@zend.com>, Joe Watkins <pthreads@pthreads.org>
   * Status: Draft   * Status: Draft
   * First Published at: http://wiki.php.net/rfc/dbc2   * First Published at: http://wiki.php.net/rfc/dbc2
  
-===== Important Note====+===== Important Note =====
  
-This RFC is a part of "Native DbC support" RFC.+This RFC is an alternative approach to "Native DbC support" RFC.
 http://wiki.php.net/rfc/dbc http://wiki.php.net/rfc/dbc
  
-There are many way to achieve DbC. This RFC proposes DbC as function/method definition.+Contracts can be defined without modification to the language, however, the D documentation calls the resulting implementation "clumsy and inconsistent".
  
-===== Introduction =====+Other advantages of a native implementation, also taken from the D manual:
  
-Design by Contract (DbC) or Contract Programming is powerful program design concept based on **Contracts** that+  * a consistent look and feel for the contracts 
 +  * tool support 
 +  * compiler optimizations 
 +  * easier management and enforcement of contracts 
 +  * handling of contract inheritance
  
-  - Define **precondition** contract for methods/functions. i.e. Define Parameter value specifications/conditions. +All of the above applies to PHP.
-  - Define **postcondition** contract for methods/functions. i.e. Define Return value specifications/conditions. +
-  - Define **invariant** contract for methods/functions. i.e. Define class state must be true always.+
  
-These contracts are evaluated development time only. Therefore, there is **no performance penalty** with DbC.+===== Introduction =====
  
-DbC changes the way program is designed.+The D manual contains the following succinct definition of contracts:
  
-  * With modularized design without DbC, the more code is consolidated, the better code is. Therefore, parameter validity is checked deep into the code. Parameter validity check is __calleE__ responsibility. +> The idea of a contract is simple - it's just an expression that must evaluate to true. If it does not, the contract is broken, and by definition, the program has a bug in it. Contracts form part of the specification for a program, moving it from the documentation to the code itself. And as every programmer knows, documentation tends to be incomplete, out of date, wrong, or non-existent. Moving the contracts into the code makes them verifiable against the program.
-  * With DbC, parameter checks are done as **precondition**. Passing valid parameter to a function is __calleR__ responsibility.+
  
-  * Without native DbC, return value validity cannot be checked without scattered assert() for every place function is used. i.e. Programmers has to write "$ret = func(); assert($ret > 0);" everywhere func() is used or func() must have assert() for every return. +This should be easily comprehensible, it further validates the argument that the best implementation is a native one, so that the programmer really can "move the specification from the documentation to the code".
-  * With native DbC, return value validity is checked as **postcondition** definition. It does not require scattered assert().+
  
-  * With native DbC, **invariant** condition may be defined. **Invariant** allows programmers consolidate class state which must be TRUE for always. e.g. $account_balance >= 0+===== Proposal =====
  
-**precondition** check can be done with assert(), but other feature requires native DbC.+Support for the following contracts will be introduced:
  
-DbC reverses the responsibility caller and callee, ensures parameters, return value and class state validity without performance penalty. This helps PHP to achieve more efficient development by contract errors, faster execution for production.+  * precondition       "require"( **precondition-expression** [,'Error msg']) 
 +  * postcondition      "return"( **return_value**, **postcondition-expression** [,'Error msg']) 
 +  * invariant          "require"( **invariant-expression** [,'Error msg'])
  
-With proper use of DbC concept, it is known **programs to be more robust/secure and faster**. Languages design lately have native DbC support. e.g. D language. Almost all languages have some kind of DbC supports today. +===== Pre and Post Condition =====
  
 +These contracts should be defined after the function declaration, but before the function body.
  
-===== Proposal =====+Multiple precondition and postcondition contracts may be used. The expressions are just a regular PHP expressions. They are evaluated in the function scope, and can access arguments and other scope variables, and return value (via a reserved name). Pre and post-conditions can't be defined for abstract methods and methods defined in interfaces.
  
-Introduce native contracts "require"(**precondition**), "return"(**postcondition**) definition to function/method and special "__invaliant()" method to class. +<code> 
- +function add(int $a, int $b) : int 
-**require**, **return** behave just like assert(). (require, return accepts message. i.e. require($a > 0, '$a must be positive') ) + require($a > 0) 
- + require($b > 0) 
-Example without **invariant** + return($ret, $ret > 0, "something wrong") 
-<code php> +{ 
-class Product { + return $a + $b; 
-  protected $inventory;+} 
 +</code>
  
-  // User is supposed to check inventory first +this code is going to be evaluated as
-  function haveEnoughInventory($quantity)  +
-    require($quantity > 0) +
-  { +
-    return (bool) ($this->inventory - $quantity) >= 0; +
-  }+
  
-  // Sell inventory +<code> 
-  function sell($quantity)  +function add(int $a, int $b) : int 
-    require($quantity > 0) +{ 
-    return($ret >= 0) // We have to think of how to specify $ret. Use block? return($ret) {assert($ret >= 0);} + assert($a > 0); 
-  { + assert($b > 0); 
-    $ret = $this>amount - $quantity; + $ret = $a + $b; 
-    return $ret; + assert($ret > 0, "something wrong"); 
-  }+ return $ret;
 } }
 </code> </code>
  
-Example with **invariant** +===== Invariant =====
-<code php> +
-class Product { +
-  protected $inventory;+
  
-  // Invariants must be TRUE for this class always  - $inventory should not be negative +Invariant contracts are declared using **require** inside class body. Multiple contracts may be used. They may access object or static properties through **$this** and **self**. Invariant contracts may be used for classes, abstract classes and traits, but not for interfaces.
-  function __invariant() { +
-    assert($this->inventory >= 0); +
-  }+
  
-  // User is supposed to check inventory first +<code> 
-  function haveEnoughInventory($quantity)  +class Accumulator { 
-    require($quantity > 0) + private $sum = 0; 
-  { +  
-    return (bool) ($this->inventory - $quantity) >= 0; + function add(int $a) 
-  }+ require($a > 0) 
 + { 
 + $this->sum += $a; 
 + }
  
-  // Sell inventory + requre($this->sum > 0, "overflow detected");
-  function sell($quantity)  +
-    require($quantity > 0) +
-  { +
-    return $this>amount - $quantity; +
-  }+
 } }
 </code> </code>
 +
 +this code is going to be evaluated as
 +
 +<code>
 +class Accumulator {
 + private $sum = 0;
 +
 + function add(int $a)
 + {
 + assert($a > 0);
 + assert($this->sum > 0, "overflow detected");
 + $this->sum += $a;
 + assert($this->sum > 0, "overflow detected");
 + }
 +}
 +</code>
 +
 +**Invariants are not evaluated when object properties are changed from outside the class scope.**
 +
 +====Contracts Inheritance Rules====
 +**TODO**
  
 ====Execution Control==== ====Execution Control====
  
-Introduce "dbc" INI switch, Off by default. No additional CLI option for DbC.+A new "dbc" INI switch is going to be introduced. It may get the following values: 
 + 
 +  * dbc=on        - generate code for contracts and check them at run-time. Program, at any time, may change this settion to dbc=off through ini_set(). 
 +  * dbc=off       - generate code for contracts but don't check them at run-time. Program, at any time, may change this settion to dbc=on through ini_set(). 
 +  * dbc=zero_cost - don't generate code for contracts. This may be set only in php.ini and can't be changed through ini_set(). 
 + 
 +  The default value if "off". 
 + 
 +===Contracts Evaluation Order=== 
 + 
 +If "dbc" is set to "on", the order of contracts validation is the following: 
 + 
 +  - all require() contracts (preconditions) defined for this methods (in defined order) 
 +  - all require() contracts (invariants) defined for this class (in defined oredrer) 
 +  - method body 
 +  - all require() contracts (invariants) defined for this class (in defined oredrer) 
 +  - all return() contracts (postconditions) defined for this methods (in defined order) 
 + 
 +**Invariant and Special Methods** 
 + 
 +  * <nowiki>__constructs()/__wakeup()/__set_state()</nowiki> will NOT execute invariant before method body. 
 +  * <nowiki>__destruct()/__sleep()</nowiki> will NOT execute invariant after method body. 
 + 
 +**Class Inheritance**
  
-A method/function is executed as follows+  * When parent class methods are called, DbC conditions are executed 
 +  * Special methods execution exception is the same
  
-===Development mode: dbc=On ===+**Static Call**
  
-  - require() conditions +  * Only pre/post contracts are executed
-  - __invariant() +
-  - method() +
-  - __invariant() +
-  - return() conditions+
  
-===Production mode: dbc=Off ===+**Interface**
  
-  - method() +  * Cannot define DbC contracts.
- +
  
 ===== Backward Incompatible Changes ===== ===== Backward Incompatible Changes =====
Line 119: Line 150:
  
   * No additional keyword   * No additional keyword
-  * __invariant() is a reserved method name 
  
 ===== Proposed PHP Version(s) ===== ===== Proposed PHP Version(s) =====
Line 133: Line 163:
  
 ==== To Opcache ==== ==== To Opcache ====
- +Opcache will have to be extended to support contracts and store them in shared memory.
-Dmitry, could you write impact when discussion is finished? +
  
 ==== New Constants ==== ==== New Constants ====
Line 141: Line 169:
  
 ==== php.ini Defaults ==== ==== php.ini Defaults ====
- +dbc=Off for all (INI_ALL)
-dbc=Off for all+
  
   * hardcoded default values   * hardcoded default values
Line 149: Line 176:
  
 ===== Open Issues ===== ===== Open Issues =====
 +  * Contracts inheritance rules 
 +  * Consider introduction of **static require()** as class invariant for static methods
   * Need to discuss syntax   * Need to discuss syntax
   * How to manage votes for 2 RFCs   * How to manage votes for 2 RFCs
- 
  
 ===== Unaffected PHP Functionality ===== ===== Unaffected PHP Functionality =====
Line 162: Line 189:
 Documentation systems may adopt native DbC syntax for documentation purpose. Documentation systems may adopt native DbC syntax for documentation purpose.
  
-===== Proposed Voting Choices ===== +===== Vote ===== 
-Include these so readers know where you are heading and can discuss the proposed voting options.+This project requires a 2/3 majority 
 + 
 +  * Option would be YES/NO only
  
-State whether this project requires a 2/3 or 50%+1 majority (see [[voting]]) 
  
 ===== Patches and Tests ===== ===== Patches and Tests =====
Line 187: Line 215:
 ===== Rejected Features ===== ===== Rejected Features =====
 Keep this updated with features that were discussed on the mail lists. Keep this updated with features that were discussed on the mail lists.
 +
rfc/dbc2.txt · Last modified: 2018/03/01 23:19 by carusogabriel

Page Tools