Annotation of libwww/Library/src/HTMemory.html, revision 2.1
2.1 ! frystyk 1: <HTML>
! 2: <HEAD>
! 3: <TITLE>Memory Management</TITLE>
! 4: <!-- Changed by: Henrik Frystyk Nielsen, 9-Feb-1996 -->
! 5: <NEXTID N="z3">
! 6: </HEAD>
! 7: <BODY>
! 8:
! 9: <H1>Dynamic Memory Interface</H1>
! 10:
! 11: <PRE>
! 12: /*
! 13: ** (c) COPYRIGHT MIT 1995.
! 14: ** Please first read the full copyright statement in the file COPYRIGH.
! 15: */
! 16: </PRE>
! 17:
! 18: This module implements a dynamic memory API thata is used in the
! 19: Library. There are three situations that are covered by this module:
! 20:
! 21: <UL>
! 22: <LI><A HREF="#d">Handling of allocation and deallocation of dynamic memory</A>
! 23: <LI><A HREF="#r">Recovering from temporary lack of available memory</A>
! 24: <LI><A HREF="#p">Panic handling in case a new allocation fails</A>
! 25: </UL>
! 26:
! 27: This module is implemented by <A HREF="HTMemory.c">HTMemory.c</A>, and it
! 28: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/"> W3C
! 29: Reference Library</A>.
! 30:
! 31: <PRE>
! 32: #ifndef HTMEMORY_H
! 33: #define HTMEMORY_H
! 34: </PRE>
! 35:
! 36: <A NAME="d"><H2>Dynamic Memory Allocation and Deallocation</H2></A>
! 37:
! 38: These are the functions for handling dynamic allocation and deallcation.
! 39:
! 40: <PRE>
! 41: extern void* HTMemory_malloc(size_t size);
! 42: extern void* HTMemory_calloc(size_t count, size_t size);
! 43: extern void* HTMemory_realloc(void * ptr, size_t size);
! 44: extern void HTMemory_free(void* ptr);
! 45: </PRE>
! 46:
! 47: <H3>Memory Macros</H3>
! 48:
! 49: We use the following set of macros throughout the code. If you don't
! 50: wany any memory management beyond normal malloc and alloc then you can
! 51: just use that instead of the HTMemory_* function.
! 52:
! 53: <PRE>
! 54: #define HT_MALLOC(size) HTMemory_malloc(size)
! 55: #define HT_CALLOC(count, size) HTMemory_calloc(count, size)
! 56: #define HT_REALLOC(ptr, size) HTMemory_realloc(ptr, size)
! 57: #define HT_FREE(pointer) {HTMemory_free(pointer);(pointer)=NULL;}
! 58: </PRE>
! 59:
! 60: <A NAME="r"><H2>Memory Freer Functions</H2></A>
! 61:
! 62: The dynamic memory freer functions are typically functions that are
! 63: capable of freeing large chunks of memory. In case a new allocation
! 64: fails, the allocation method looks for any freer functions to
! 65: call. There can be multriple freer functions and after each call, the
! 66: allocation method tries again to allocate the desired amount of
! 67: dynamic memory. The freer functions are called in <EM>reverse</EM>
! 68: order meaning that the <EM>last</EM> one registered gets called
! 69: <EM>first</EM>. That way, it is easy to add temporary free functions
! 70: which then are guaranteed to be called first if a methods fails.
! 71:
! 72: <H3>Add a Freer Function</H3>
! 73:
! 74: You can add a freer function by using the following method. The
! 75: Library itself registeres a set of free functions during
! 76: initialization. If the application does not register any freer
! 77: functions then the Library looks how it can free internal memory.
! 78:
! 79: <PRE>
! 80: typedef void HTMemoryCallback(size_t size);
! 81:
! 82: extern BOOL HTMemoryCall_add (HTMemoryCallback * cbf);
! 83: </PRE>
! 84:
! 85: <H3>Delete a Freer Function</H3>
! 86:
! 87: Freer functions can be deleted at any time in which case they are not
! 88: called anymore.
! 89:
! 90: <PRE>
! 91: extern BOOL HTMemoryCall_delete (HTMemoryCallback * cbf);
! 92: extern BOOL HTMemoryCall_deleteAll (void);
! 93: </PRE>
! 94:
! 95: <A NAME="p"><H2>Panic Handling</H2></A>
! 96:
! 97: If the freer functions are not capable of deallocation enough memory
! 98: then the application must have an organized way of closing down. This
! 99: is done using the panic handler. In the libwww, each allocation is
! 100: tested and HT_OUTOFMEM is called if a NULL was returned. HT_OUTOFMEM
! 101: is a macro which calls HTMemory_outofmem. This function calls an exit
! 102: function defined by the app in a call to HTMemory_setExit. If the app
! 103: has not defined this function, HTMemory_outofmem TTYPrints the error
! 104: message and calls exit(1).
! 105:
! 106: <PRE>
! 107: typedef void HTMemory_exit_callback(char * name, char * file, unsigned long line);
! 108: extern void HTMemory_setExit(HTMemory_exit_callback * pExit);
! 109: extern HTMemory_exit_callback * HTMemory_exit(void);
! 110: extern void HTMemory_outofmem(char * name, char * file, unsigned long line);
! 111: #define HT_OUTOFMEM(name) HTMemory_outofmem(name, __FILE__, __LINE__)
! 112: </PRE>
! 113:
! 114: <PRE>
! 115: #endif /* HTMEMORY_H */
! 116: </PRE>
! 117:
! 118: End of declaration
! 119: </BODY>
! 120: </HTML>
Webmaster
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to HTMemory.html CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / libwww / Library / src