added documentation for __pragma__ ('opov','fast')
@@ -319,6 +319,37 @@ These operators have been chosen since they can enhance the readability of compu
Formula v4 = M \* (v1 + v2) + v3 is probably preferred over v4 = add (mul (M, add (v1, v2), v3)), which by the way closely resembles the JavaScript that will be generated for the expression that uses overloaded + and \* operators. In order to support operator overloading your matrix and vector classes have to support the appropriate selection of functions out of *__mul__*, *__rmul__*, *__div__*, *__rdiv__*, *__add__*, *__radd__*, *__sub__*, *__rsub__*, *__matmul__*, *__rmatmul__*, *__getitem__*, *__setitem__* and *__call__* as described in the CPython documentation. The comparison operators are supported by the functions *__eq__*, *__ne__*, *__lt__*, *__le__*, *__gt__* and *__ge__*.
Note that the pragma needs to be applied where the operators are *used*, not where they are defined.
+
+By default, *__pragma__ ('opov')* uses a generalized method to support the widest range of Python syntax. However the default operator overloading method adds one or more extra function calls to make sure that any valid python line can be properly overloaded in Javascript. In performance code the extra function calls can exact a noticeable performance penalty.
+
+There's a less general but faster variant of the the pragma which looks like this: *__pragma__ ('opov','fast')* The fast alternative avoids the extra function calls and is notably faster for large iteration counts. However it has one important limitation: the left hand side of any expression being overloaded *cannot be a number or string literal*. So, this will work, assuming our python objects have defined the *__add__* magic method:
+
+.. code-block:: python
+
+ result = SomePythonObject + SomeOtherPythonObject
+
+And this will also work:
+
+.. code-block:: python
+
+ result = SomePythonObject + 5
+
+but the fast overload will *not* work for this:
+
+.. code-block:: python
+
+ result = 5 + SomePythonObject
+
+As in Python, if the left hand operand is a number and you want an overloaded function on the right hand operand, you need to implement the appropriate 'r' version of the magic method such as *__radd__* or *__rmul__*. So
+
+.. code-block:: python
+
+ number = 5
+ result = number + SomePythonObject
+
+will work if `SomePythonObject` implements `\_\_radd\_\_`.
+
+
.. _skipping_fragments:
Skipping fragments while generating code : __pragma__ ('skip') and __pragma__ ('noskip')
