[pypy-commit] pypy default: Fixed formatting issues in doc file.

[anton_gulenko]

Author: Anton Gulenko <anton.gulenko at googlemail.com>
Branch: 
Changeset: r76879:83b5d7b51f28
Date: 2015-03-12 14:52 +0100
http://bitbucket.org/pypy/pypy/changeset/83b5d7b51f28/

Log:	Fixed formatting issues in doc file. Added example code for the
	Usage-walkthrough.

diff --git a/rpython/doc/rstrategies.rst b/rpython/doc/rstrategies.rst
--- a/rpython/doc/rstrategies.rst
+++ b/rpython/doc/rstrategies.rst
@@ -21,7 +21,7 @@
 here <https://github.com/antongulenko/pycket/tree/rstrategies>`__).
 
 Concept
-^^^^^^^
+-------
 
 Collections are often used homogeneously, i.e. they contain only objects
 of the same type. Primitive numeric types like ints or floats are
@@ -35,7 +35,7 @@
 require converting the storage array.
 
 Usage
------
+~~~~~
 
 The following are the steps needed to integrated rstrategies in an
 RPython VM. Because of the special nature of this library it is not
@@ -46,15 +46,15 @@
 The sequence of steps described here is something like a "setup
 walkthrough", and might be a bit abstract. To see a concrete example,
 look at
-`AbstractShadow <https://github.com/HPI-SWA-Lab/RSqueak/blob/d5ff2572106d23a5246884de6f8b86f46d85f4f7/spyvm/storage.py#L73>`__,
-`StrategyFactory <https://github.com/HPI-SWA-Lab/RSqueak/blob/d5ff2572106d23a5246884de6f8b86f46d85f4f7/spyvm/storage.py#L126>`__
+`SingletonStorageStrategy <https://github.com/HPI-SWA-Lab/RSqueak/blob/d048f713002c01c9b121c80e8eb9bea33ed742d6/spyvm/storage.py#L73>`__,
+`StrategyFactory <https://github.com/HPI-SWA-Lab/RSqueak/blob/d048f713002c01c9b121c80e8eb9bea33ed742d6/spyvm/storage.py#L126>`__
 and
-`W\_PointersObject <https://github.com/HPI-SWA-Lab/RSqueak/blob/d5ff2572106d23a5246884de6f8b86f46d85f4f7/spyvm/model.py#L565>`__
+`W\_PointersObject <https://github.com/HPI-SWA-Lab/RSqueak/blob/d048f713002c01c9b121c80e8eb9bea33ed742d6/spyvm/model.py#L616>`__
 from the `RSqueak VM <https://github.com/HPI-SWA-Lab/RSqueak>`__. The
 code is also well commented.
 
 Basics
-^^^^^^
+-------
 
 Currently the rstrategies library supports fixed sized and variable
 sized collections. This can be used to optimize a wide range of
@@ -94,23 +94,37 @@
 Also implement a ``storage_factory()`` method, which returns an instance
 of ``rstrategies.StorageFactory``, which is described below.
 
+An example ``AbstractStrategy`` class, which also stores an additional ``space`` parameter could looks like this:
+
+::
+
+class AbstractStrategy(AbstractStrategy):
+    _attrs_ = ['space']
+    _immutable_fields_ = ['space']
+    __metaclass__ = rstrat.StrategyMetaclass
+    import_from_mixin(rstrat.AbstractStrategy)
+    import_from_mixin(rstrategies.SafeIndexingMixin)
+    
+    def __init__(self, space):
+        self.space = space
+    
+    def strategy_factory(self):
+        return self.space.strategy_factory
+
+
 Strategy classes
-^^^^^^^^^^^^^^^^
+----------------
 
 Now you can create the actual strategy classes, subclassing them from
 the single root class. The following list summarizes the basic
-strategies available. \* ``EmptyStrategy`` A strategy for empty
-collections; very efficient, but limited. Does not allocate anything. \*
-``SingleValueStrategy`` A strategy for collections containing the same
-object ``n`` times. Only allocates memory to store the size of the
-collection. \* ``GenericStrategy`` A non-optimized strategy backed by a
-generic python list. This is the fallback strategy, since it can store
-everything, but is not optimized. \* ``WeakGenericStrategy`` Like
-``GenericStrategy``, but uses ``weakref`` to hold on weakly to its
-elements. \* ``SingleTypeStrategy`` Can store a single unboxed type like
-int or float. This is the main \* ``TaggingStrategy`` Extension of
-SingleTypeStrategy. Uses a specific value in the value range of the
-unboxed type to represent one additional, arbitrary object.
+strategies available.
+
+- ``EmptyStrategy`` A strategy for empty collections; very efficient, but limited. Does not allocate anything.
+- ``SingleValueStrategy`` A strategy for collections containing the same object ``n`` times. Only allocates memory to store the size of the collection.
+- ``GenericStrategy`` A non-optimized strategy backed by a generic python list. This is the fallback strategy, since it can store everything, but is not optimized.
+- ``WeakGenericStrategy`` Like ``GenericStrategy``, but uses ``weakref`` to hold on weakly to its elements.
+- ``SingleTypeStrategy`` Can store a single unboxed type like int or float. This is the main optimizing strategy
+- ``TaggingStrategy`` Extension of SingleTypeStrategy. Uses a specific value in the value range of the unboxed type to represent one additional, arbitrary object. For example, one of ``float``'s ``NaN`` representations can be used to represent special value like ``nil``.
 
 There are also intermediate classes, which allow creating new, more
 customized strategies. For this, you should get familiar with the code.
@@ -118,7 +132,7 @@
 Include one of these mixin classes using ``import_from_mixin``. The
 mixin classes contain comments describing methods or fields which are
 also required in the strategy class in order to use them. Additionally,
-add the @rstrategies.strategy(generalize=alist) decorator to all
+add the ``@rstrategies.strategy(generalize=alist)`` decorator to all
 strategy classes. The ``alist`` parameter must contain all strategies,
 which the decorated strategy can switch to, if it can not represent a
 new element anymore.
@@ -126,8 +140,21 @@
 for an implemented strategy. See the other strategy classes behind this
 link for more examples.
 
+An example strategy class for optimized ``int`` storage could look like this:
+
+::
+
+ at rstrat.strategy(generalize=[GenericStrategy])
+class IntegerOrNilStrategy(AbstractStrategy):
+    import_from_mixin(rstrat.TaggingStrategy)
+    contained_type = model.W_Integer
+    def wrap(self, val): return self.space.wrap_int(val)
+    def unwrap(self, w_val): return self.space.unwrap_int(w_val)
+    def wrapped_tagged_value(self): return self.space.w_nil
+    def unwrapped_tagged_value(self): return constants.MAXINT
+
 Strategy Factory
-^^^^^^^^^^^^^^^^
+----------------
 
 The last part is subclassing ``rstrategies.StrategyFactory``,
 overwriting the method ``instantiate_strategy`` if necessary and passing
@@ -137,12 +164,46 @@
 mechanism behind strategies. See the comments in the source code.
 
 The strategy mixins offer the following methods to manipulate the
-contents of the collection: \* basic API \* ``size`` \* fixed size API
-\* ``store``, ``fetch``, ``slice``, ``store_all``, ``fetch_all`` \*
-variable size API \* ``insert``, ``delete``, ``append``, ``pop``
+contents of the collection:
+
+- basic API
+
+  - ``size``
+
+- fixed size API
+
+  - ``store``, ``fetch``, ``slice``, ``store_all``, ``fetch_all``
+
+- variable size API
+
+  - ``insert``, ``delete``, ``append``, ``pop``
 
 If the collection has a fixed size, simply never use any of the variable
 size methods in the VM code. Since the strategies are singletons, these
 methods need the collection object as first parameter. For convenience,
 more fitting accessor methods should be implemented on the collection
 class itself.
+
+An example strategy factory for the ``AbstractStrategy`` class above could look like this:
+
+::
+
+class StrategyFactory(rstrategies.StrategyFactory):
+    _attrs_ = ['space']
+    _immutable_fields_ = ['space']
+    
+    def __init__(self, space):
+        self.space = space
+        rstrat.StrategyFactory.__init__(self, AbstractStrategy)
+    
+    def instantiate_strategy(self, strategy_type):
+        return strategy_type(self.space)
+    
+    def strategy_type_for(self, list_w, weak=False):
+        """
+        Helper method for handling weak objects specially
+        """
+        if weak:
+            return WeakListStrategy
+        return rstrategies.StrategyFactory.strategy_type_for(self, list_w)
+    
\ No newline at end of file