[Python-checkins] CVS: python/nondist/peps pep-0253.txt,1.4,1.5

2001年6月14日 06:37:47 -0700

Update of /cvsroot/python/python/nondist/peps
In directory usw-pr-cvs1:/tmp/cvs-serv10803
Modified Files:
	pep-0253.txt 
Log Message:
Clarified the paragraph about creating a subtype in C.
Index: pep-0253.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/peps/pep-0253.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -r1.4 -r1.5
*** pep-0253.txt	2001年06月13日 21:48:31	1.4
--- pep-0253.txt	2001年06月14日 13:37:45	1.5
***************
*** 369,372 ****
--- 369,377 ----
 Creating a subtype of a built-in type in C

+ Let's assume we're deriving from a mutable base type whose
+ tp_itemsize is zero. The subtype code is not GC-aware, although
+ it may inherit GC-awareness from the base type (this is
+ automatic). The base type's allocation uses the standard heap.
+ 
 The derived type begins by declaring a type structure which
 contains the base type's structure. For example, here's the type
***************
*** 391,433 ****
 into it. Some fields that must be initialized properly:

! - the object header must be filled in as usual; the type should be
! PyType_Type

! - the tp_basicsize field must be set to the size of the subtype
! instances

! - the tp_base field must be set to the address of the base type's
! type object

! - the tp_dealloc slot function must be a deallocation function for
! the subtype

! - the tp_flags field must be set to the usual Py_TPFLAGS_DEFAULT
! value

! - the tp_name field must be set (otherwise it will be inherited,
! which is wrong)

 Exception: if the subtype defines no additional fields in its
 structure (i.e., it only defines new behavior, no new data), the
! tp_basicsize and the tp_dealloc fields may be set to zero. In
! order to complete the initialization of the type,
 PyType_InitDict() must be called. This replaces zero slots in the
! subtype with the value of the corresponding base type slots. It
! also fills in tp_dict, the type's dictionary; this is more a
! matter of pep-0252.
! 
! The subtype's tp_dealloc slot deserves special attention. It must
! uninitialize and deallocate the object in an orderly manner: first
! it must uninitialize the fields added by the extension type; then
! it must call the base type's tp_clear function; finally it must
! deallocate the memory of the object. Usually, the base type's
! tp_clear function has no global name; it is permissible to call it
! via the base type's tp_clear slot, e.g. PyListType.tp_clear(obj).
! Only if it is known that the base type uses the same allocation
! method as the subtype and the subtype requires no uninitialization
! (e.g. it adds no data fields or all its data fields are numbers)
! is it permissible to leave tp_dealloc set to zero in the subtype's
! type object; it will be copied from the base type.

 A subtype is not usable until PyType_InitDict() is called for it;
--- 396,447 ----
 into it. Some fields that must be initialized properly:

! - The object header must be filled in as usual; the type should be
! &PyType_Type.

! - The tp_basicsize field must be set to the size of the subtype
! instance struct (in the above example: sizeof(spamlistobject)).

! - The tp_base field must be set to the address of the base type's
! type object.

! - If the derived slot defines any pointer fields, the tp_dealloc
! slot function requires special attention, see below; otherwise,
! it can be set to zero, to inherit the base type's deallocation
! function.

! - The tp_flags field must be set to the usual Py_TPFLAGS_DEFAULT
! value.

! - The tp_name field must be set; it is recommended to set tp_doc
! as well (these are not inherited).

 Exception: if the subtype defines no additional fields in its
 structure (i.e., it only defines new behavior, no new data), the
! tp_basicsize and the tp_dealloc fields may be set to zero.
! 
! In order to complete the initialization of the type,
 PyType_InitDict() must be called. This replaces zero slots in the
! subtype with the value of the corresponding base type slots. (It
! also fills in tp_dict, the type's dictionary, and does various
! other initializations necessary for type objects.)
! 
! The subtype's tp_dealloc slot deserves special attention. If the
! derived type defines no additional pointers that need to be
! DECREF'ed or freed when the object is deallocated, it can be set
! to zero. Otherwise, the subtype's deallocation function must call
! Py_XDECREF() for any PyObject * fields and the correct memory
! freeing function for any other pointers it owns, and then call the
! base class's tp_dealloc slot. Because deallocation functions
! typically are not exported, this call has to be made via the base
! type's type structure, e.g., when deriving from the standard list
! type:
! 
! PyList_Type.tp_dealloc(self);
! 
! (If the subtype uses a different allocation heap than the base
! type, the subtype must call the base type's tp_clear() slot
! instead, followed by a call to free the object's memory from the
! appropriate heap, e.g. PyObject_DEL(self) if the subtype uses the
! standard heap. But in this case subtyping is not recommended.)

 A subtype is not usable until PyType_InitDict() is called for it;
***************
*** 440,448 ****
 calls, a test for tp_dict==NULL can be made.

! If the subtype itself should be subtypable (usually desirable), it
! should follow the same rules are given above for base types: have
! a tp_construct that accepts a preallocated object and calls the
! base type's tp_construct, and have a tp_clear that calls the base
! type's tp_clear.

--- 454,464 ----
 calls, a test for tp_dict==NULL can be made.

! To create a subtype instance, the base type's tp_alloc slot must
! be called with the subtype as its first argument. Then, if the
! base type has a tp_init slot, that must be called to initialize
! the base portion of the instance; finally the subtype's own fields
! must be initialized. After allocation, the initialization can
! also be done by calling the subtype's tp_init slot, assuming this
! correctly calls its base type's tp_init slot.