classification
Title: Example in C-API memory management doc has confusing order
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.snow, skrah
Priority: low Keywords:

Created on 2013-01-26 18:20 by eric.snow, last changed 2013-01-27 00:14 by eric.snow. This issue is now closed.

Messages (5)
msg180697 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2013-01-26 18:20
In http://docs.python.org/dev/c-api/memory.html#examples:

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Is there a good reason to have the second set of 3 lines in the opposite order as the first three?  At first I missed that they were in a different order and thought there was an error in the example.  If there's no good reason for the order, it would be worth fixing.  If there is a good reason,  a comment in the example would help.  Either way I'd be glad to patch it (will go ahead with fixing the ordering later today if no one does it first).
msg180698 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2013-01-26 18:36
Please don't change this: It's a common pattern in C to undo memory
allocations in the opposite order.
msg180719 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2013-01-26 22:58
Thanks for clarifying, Stefan.  Are you opposed to a comment in the example?
msg180722 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2013-01-26 23:55
Moderately opposed, yes. PyMem_Malloc()/PyMem_Free() and PyMem_New()/PyMem_Del()
are already explained in depth above.
msg180724 - (view) Author: Eric Snow (eric.snow) * (Python committer) Date: 2013-01-27 00:14
Sorry, I'd meant something like this:

vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
char *buf1 = PyMem_New(char, BUFSIZ);
char *buf2 = (char *) malloc(BUFSIZ);
char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
...
/* in reverse order */
PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
free(buf2);       /* Right -- allocated via malloc() */
free(buf1);       /* Fatal -- should be PyMem_Del()  */
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This will help if someone does not know the common pattern.
History
Date User Action Args
2013-01-27 00:14:02eric.snowsetmessages: + msg180724
2013-01-26 23:55:23skrahsetmessages: + msg180722
2013-01-26 22:58:35eric.snowsetmessages: + msg180719
2013-01-26 18:42:00ezio.melottisetstatus: open -> closed
type: enhancement
resolution: rejected
stage: needs patch -> resolved
2013-01-26 18:36:11skrahsetnosy: + skrah
messages: + msg180698
2013-01-26 18:20:37eric.snowcreate