Ticket #715: trac_715-reviewer.patch

File trac_715-reviewer.patch, 11.7 KB (added by jpflori, 9 years ago)

Reviewer patch; added doc

  • sage/categories/action.pyx 

    # HG changeset patch
# User Jean-Pierre Flori <jean-pierre.flor@ssi.gouv.fr>
# Date 1331128122 -3600
# Node ID 36c211dc61a6bf79dee93a227a37f23e9dd7de23
# Parent  d3c9efea86f7440332b9c43d9dc3e4dafd38a73d
#715: Reviewer patch -- minor typos and additional doc

diff --git a/sage/categories/action.pyx b/sage/categories/action.pyx
    a b  
    11r"""
    2 Group, ring, etc. actions on objects. 
     2Group, ring, etc. actions on objects.
    33
    4 The terminology and notation used is suggestive of groups
    5 acting on sets, but this framework can be used for modules,
    6 algebras, etc.
     4The terminology and notation used is suggestive of groups acting on sets,
     5but this framework can be used for modules, algebras, etc.
    76
    8 A group action $G \times S \rightarrow S$ is a functor from $G$ to Sets. 
     7A group action $G \times S \rightarrow S$ is a functor from $G$ to Sets.
    98
    10 AUTHORS:
    11     -- Robert Bradshaw: initial version
     9.. WARNING::
     10
     11    An :class:`Action` object only keeps a weak reference to the underlying set
     12    which is acted upon. This decision was made in :trac:`715` in order to
     13    allow garbage collection within the coercion framework (this is where
     14    actions are mainly used) and avoid memory leaks.
     15
     16    ::
     17
     18        sage: from sage.categories.action import Action
     19        sage: class P: pass
     20        sage: A = Action(P(),P())
     21        sage: import gc
     22        sage: _ = gc.collect()
     23        sage: A
     24        Traceback (most recent call last):
     25        ...
     26        RuntimeError: This action acted on a set that became garbage collected
     27
     28    To avoid garbage collection of the underlying set, it is sufficient to
     29    create a strong reference to it before the action is created.
     30
     31    ::
     32
     33        sage: _ = gc.collect()
     34        sage: from sage.categories.action import Action
     35        sage: class P: pass
     36        sage: q = P()
     37        sage: A = Action(P(),q)
     38        sage: gc.collect()
     39        0
     40        sage: A
     41        Left action by <__main__.P instance at ...> on <__main__.P instance at ...>
     42
     43AUTHOR:
     44
     45- Robert Bradshaw: initial version
    1246"""
    1347
    1448#*****************************************************************************
    … …  
    130164            sage: A.left_domain() is R
    131165            True
    132166
    133         By trac ticket #715, there is only a weak reference to the underlying
    134         set. Hence, the underlying set may be garbage collected, even when the
     167        By :trac:`715`, there is only a weak reference to the underlying set.
     168        Hence, the underlying set may be garbage collected, even when the
    135169        action is still alive. This may result in a runtime error, as follows::
    136170
    137171            sage: from sage.categories.action import Action
    … …  
    143177            Left action by <__main__.P instance at ...> on <__main__.P instance at ...>
    144178            sage: del q
    145179            sage: import gc
    146             sage: n = gc.collect()
     180            sage: _ = gc.collect()
    147181            sage: A
    148182            Traceback (most recent call last):
    149183            ...

  • sage/matrix/action.pyx 

    diff --git a/sage/matrix/action.pyx b/sage/matrix/action.pyx
    a b  
    11"""
    2 These are the actions used by the coercion model for matrix and vector multiplications.
     2These are the actions used by the coercion model for matrix and vector
     3multiplications.
    34
    4 AUTHORS:
    5     -- Robert Bradshaw (2007-09): Initial version.
     5.. WARNING::
     6
     7    The class :class:`MatrixMulAction` and its descendants extends the class
     8    :class:`Action`. As a cosnequence objects from these classes only keep weak
     9    references to the underlying sets which are acted upon. This decision was
     10    made in :trac:`715` in order to allow garbage collection within the coercion
     11    framework, where actions are mainly used, and avoid memory leaks.
     12
     13    To ensure that the underlying set of such an object does not get garbage
     14    collected, it is sufficient to explicitely create a strong reference to it
     15    before creating the action.
     16
     17    ::
     18
     19        sage: MSQ = MatrixSpace(QQ, 2)
     20        sage: MSZ = MatrixSpace(ZZ['x'], 2)
     21        sage: A = MSQ.get_action(MSZ)
     22        sage: A
     23        Left action by Full MatrixSpace of 2 by 2 dense matrices over Rational Field on Full MatrixSpace of 2 by 2 dense matrices over Univariate Polynomial Ring in x over Integer Ring
     24        sage: import gc
     25        sage: _ = gc.collect()
     26        sage: A
     27        Left action by Full MatrixSpace of 2 by 2 dense matrices over Rational Field on Full MatrixSpace of 2 by 2 dense matrices over Univariate Polynomial Ring in x over Integer Ring
     28
     29.. NOTE::
     30
     31    The :func:`MatrixSpace` function caches the objects it creates. Therefore,
     32    the underlying set ``MSZ`` in the above example will not be garbage
     33    collected, even if it is not strongly ref'ed. Nonetheless, there is no
     34    guarantee that the set that is acted upon will always be cached in such a
     35    way, so that following the above example is good practice.
     36
     37AUTHOR:
     38
     39- Robert Bradshaw (2007-09): Initial version.
    640"""
    741
    842#*****************************************************************************
    … …  
    4074        """
    4175        EXAMPLES:
    4276
    43         By trac ticket #715, there only is a weak reference on the underlying set,
    44         so that it can be garbage collected if only the action itself is explicitly
    45         referred to. Hence, we first assign the involved matrix spaces to a
    46         variable::
     77        By :trac:`715`, there only is a weak reference on the underlying set,
     78        so that it can be garbage collected if only the action itself is
     79        explicitly referred to. Hence, we first assign the involved matrix
     80        spaces to a variable::
    4781
    4882            sage: MSQ = MatrixSpace(QQ, 2)
    4983            sage: MSZ = MatrixSpace(ZZ['x'], 2)
    … …  
    5589            Full MatrixSpace of 2 by 2 dense matrices over Univariate Polynomial Ring in x over Integer Ring
    5690            sage: A.codomain()
    5791            Full MatrixSpace of 2 by 2 dense matrices over Univariate Polynomial Ring in x over Rational Field
     92
     93        .. NOTE::
     94
     95            The :func:`MatrixSpace` function caches the object it creates.
     96            Therefore, the underlying set ``MSZ`` in the above example will not
     97            be garbage collected, even if it is not strongly ref'ed.
     98            Nonetheless, there is no guarantee that the set that is acted upon
     99            will always be cached in such a way, so that following the above
     100            example is good practice.
     101
    58102        """
    59103        return self.underlying_set()
    60104
    … …  
    64108        """
    65109        EXAMPLES:
    66110
    67         By trac ticket #715, there only is a weak reference on the underlying set,
    68         so that it can be garbage collected if only the action itself is explicitly
    69         referred to. Hence, we first assign the involved matrix spaces to a
    70         variable::
     111        By :trac:`715`, there only is a weak reference on the underlying set,
     112        so that it can be garbage collected if only the action itself is
     113        explicitly referred to. Hence, we first assign the involved matrix
     114        spaces to a variable::
    71115
    72116            sage: R.<x> = ZZ[]
    73117            sage: MSR = MatrixSpace(R, 3, 3)
    … …  
    81125            [  0   x]
    82126            [2*x 3*x]
    83127            [4*x 5*x]
     128
     129        .. NOTE::
     130
     131            The :func:`MatrixSpace` function caches the object it creates.
     132            Therefore, the underlying set ``MSZ`` in the above example will not
     133            be garbage collected, even if it is not strongly ref'ed.
     134            Nonetheless, there is no guarantee that the set that is acted upon
     135            will always be cached in such a way, so that following the above
     136            example is good practice.
     137
    84138        """
    85139        if not is_MatrixSpace(S):
    86140            raise TypeError, "Not a matrix space: %s" % S
    … …  
    90144        """
    91145        EXAMPLES:
    92146
    93         By trac ticket #715, there only is a weak reference on the underlying set,
    94         so that it can be garbage collected if only the action itself is explicitly
    95         referred to. Hence, we first assign the involved matrix spaces to a
    96         variable::
     147        By :trac:`715`, there only is a weak reference on the underlying set,
     148        so that it can be garbage collected if only the action itself is
     149        explicitly referred to. Hence, we first assign the involved matrix
     150        spaces to a variable::
    97151
    98152            sage: from sage.matrix.action import MatrixMatrixAction
    99153            sage: R.<x> = ZZ[]
    … …  
    103157            Left action by Full MatrixSpace of 3 by 3 dense matrices over Univariate Polynomial Ring in x over Integer Ring on Full MatrixSpace of 3 by 2 dense matrices over Rational Field
    104158            sage: A.codomain()
    105159            Full MatrixSpace of 3 by 2 dense matrices over Univariate Polynomial Ring in x over Rational Field
     160
     161        .. NOTE::
     162
     163            The :func:`MatrixSpace` function caches the object it creates.
     164            Therefore, the underlying set ``MSZ`` in the above example will not
     165            be garbage collected, even if it is not strongly ref'ed.
     166            Nonetheless, there is no guarantee that the set that is acted upon
     167            will always be cached in such a way, so that following the above
     168            example is good practice.
     169
    106170        """
    107171        if self.G.ncols() != self.underlying_set().nrows():
    108172            raise TypeError, "incompatible dimensions %s, %s" % (self.G.ncols(),  self.underlying_set().nrows())

  • sage/structure/coerce_dict.pyx 

    diff --git a/sage/structure/coerce_dict.pyx b/sage/structure/coerce_dict.pyx
    a b  
    2424    """
    2525    Erases items from a :class:`TripleDict` when a weak reference becomes invalid.
    2626
    27     This is of internal use only. Instances of this class will be passed as a callback
    28     function when creating a weak reference.
     27    This is of internal use only. Instances of this class will be passed as a
     28    callback function when creating a weak reference.
    2929
    3030    EXAMPLES::
    3131
    … …  
    4646
    4747    AUTHOR:
    4848
    49     Simon King (2012-01)
     49    - Simon King (2012-01)
    5050    """
    5151
    5252    def __init__(self, D):
    … …  
    6464
    6565        """
    6666        self.D = D
     67
    6768    def __call__(self, r):
    6869        """
    6970        INPUT:
    7071
    7172        A weak reference with key.
    7273
    73         When this is called with a weak reference ``r``, then each item containing ``r``
    74         is removed from the associated :class:`TripleDict`. Normally, this only happens
    75         when a weak reference becomes invalid.
     74        When this is called with a weak reference ``r``, then each item
     75        containing ``r`` is removed from the associated :class:`TripleDict`.
     76        Normally, this only happens when a weak reference becomes invalid.
    7677
    7778        EXAMPLES::
    7879
    … …  
    195196    Note that this kind of dictionary is also used for caching actions
    196197    and coerce maps. In previous versions of Sage, the cache was by
    197198    strong references and resulted in a memory leak in the following
    198     example. However, this leak was fixed by trac ticket #715, using
    199     weak references::
     199    example. However, this leak was fixed by trac ticket :trac:`715`,
     200    using weak references::
    200201
    201202        sage: K = GF(1<<55,'t')
    202203        sage: for i in range(50):
    … …  
    211212        sage: len(LE)    # indirect doctest
    212213        1
    213214
    214     AUTHOR::
     215    AUTHORS:
    215216
    216217    - Robert Bradshaw, 2007-08
     218
    217219    - Simon King, 2012-01
    218220    """
    219221   
    … …  
    261263        """
    262264        The distribution of items in buckets.
    263265       
    264         OUTPUT::
     266        OUTPUT:
    265267
    266268        - (min, avg, max)
    267269       
    … …  
    300302       
    301303        OUTPUT:
    302304       
    303         A list of how many items are in each bucket. 
     305        A list of how many items are in each bucket.
    304306       
    305307        EXAMPLES::
    306308