Ticket #715: trac_715_specification.patch

File trac_715_specification.patch, 2.6 KB (added by SimonKing, 7 years ago)

Document the specifications of TripleDict

  • doc/en/reference/structure.rst

    # HG changeset patch
    # User Simon King <simon.king@uni-jena.de>
    # Date 1345141378 -7200
    # Node ID 6658e3bc3e1f9c6d8eb2176895842e4ef04d4484
    # Parent  8a55ce250af80970145c467e6a35bf6794800218
    #715: Documentation of TripleDict
    
    diff --git a/doc/en/reference/structure.rst b/doc/en/reference/structure.rst
    a b  
    99   sage/structure/parent_old
    1010   sage/structure/parent_base
    1111   sage/structure/parent_gens
     12   sage/structure/coerce_dict
    1213   sage/structure/formal_sum
    1314   sage/structure/factorization
    1415   sage/structure/element
  • sage/structure/coerce_dict.pyx

    diff --git a/sage/structure/coerce_dict.pyx b/sage/structure/coerce_dict.pyx
    a b  
    11#*****************************************************************************
    22#       Copyright (C) 2007 Robert Bradshaw <robertwb@math.washington.edu>
    3 #                     2011 Simon King <simon.king@uni-jena.de>
     3#                     2012 Simon King <simon.king@uni-jena.de>
    44#
    55#  Distributed under the terms of the GNU General Public License (GPL)
    66#
    77#                  http://www.gnu.org/licenses/
    88#*****************************************************************************
     9"""
     10Containers for storing coercion data
    911
     12This module provides :class:`TripleDict`. It is a structure similar to
     13``WeakKeyDictionary`` in Python's weakref module, and is optimized for lookup
     14speed. Keys consist of a triple (k1,k2,k3) and are looked up by identity
     15rather than equality. The keys are stored by weakrefs if possible. If any
     16one of the components k1, k2, k3 gets garbage collected, then the entry is
     17removed from the :class:`TripleDict`.
    1018
     19Key components that do not allow for weakrefs are stored via a normal
     20refcounted reference. That means that any entry stored using a triple
     21(k1,k2,k3) so that none of the k1,k2,k3 allows a weak reference behaves
     22as an entry in a normal dictionary: Its existence in :class:`TripleDict`
     23prevents it from being garbage collected.
     24
     25That container currently is used to store coercion and conversion maps
     26between two parents (:trac:`715`) and to store homsets of pairs of objects
     27of a category (:trac:`11521`). In both cases, it is essential that the parent
     28structures remain garbage collectable, it is essential that the data access
     29is faster than with a usual ``WeakKeyDictionary``, and we enforce the "unique
     30parent condition" in Sage (parent structures should be identical if they are
     31equal).
     32"""
    1133include "../ext/python_list.pxi"
    1234
    1335from sage.misc.constant_function import ConstantFunction