Add two scenarios by Vladimir Marangozov that show how to use your own

allocator.

Include/mymalloc.h

@@ -95,7 +95,10 @@ extern "C" {
 
    The PyCore_* macros can be defined to make the interpreter use a
    custom allocator. Note that they are for internal use only. Both
-   the core and extension modules should use the PyMem_* API. */
+   the core and extension modules should use the PyMem_* API.
+
+   See the comment block at the end of this file for two scenarios
+   showing how to use this to use a different allocator. */
 
 #ifndef PyCore_MALLOC_FUNC
 #undef PyCore_REALLOC_FUNC
@@ -200,4 +203,43 @@ extern DL_IMPORT(void) PyMem_Free Py_PROTO((ANY *));
 }
 #endif
 
+/* SCENARIOS
+
+   Here are two scenarios by Vladimir Marangozov (the author of the
+   memory allocation redesign).
+
+   1) Scenario A
+
+   Suppose you want to use a debugging malloc library that collects info on
+   where the malloc calls originate from. Assume the interface is:
+
+   d_malloc(size_t n, char* src_file, unsigned long src_line) c.s.
+
+   In this case, you would define (for example in config.h) :
+
+   #define PyCore_MALLOC_FUNC      d_malloc
+   ...
+   #define PyCore_MALLOC_PROTO	Py_PROTO((size_t, char *, unsigned long))
+   ...
+   #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
+
+   #define PyCore_MALLOC(n)	PyCore_MALLOC_FUNC((n), __FILE__, __LINE__)
+   ...
+
+   2) Scenario B
+
+   Suppose you want to use malloc hooks (defined & initialized in a 3rd party
+   malloc library) instead of malloc functions.  In this case, you would
+   define:
+
+   #define PyCore_MALLOC_FUNC	(*malloc_hook)
+   ...
+   #define NEED_TO_DECLARE_MALLOC_AND_FRIEND
+
+   and ignore the previous definitions about PyCore_MALLOC_FUNC, etc.
+
+
+*/
+
+
 #endif /* !Py_MYMALLOC_H */