Annotation of libwww/Library/src/HTMemory.html, revision 2.7
2.1 frystyk 1: <HTML>
2: <HEAD>
2.7 ! frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 6-Apr-1996 -->
! 4: <TITLE>W3C Reference Library libwww Dynamic Memory Handlers</TITLE>
2.1 frystyk 5: </HEAD>
6: <BODY>
2.7 ! frystyk 7: <H1>
! 8: Dynamic Memory Handlers
! 9: </H1>
2.1 frystyk 10: <PRE>
11: /*
12: ** (c) COPYRIGHT MIT 1995.
13: ** Please first read the full copyright statement in the file COPYRIGH.
14: */
15: </PRE>
2.7 ! frystyk 16: <P>
! 17: This module defines any memory handler to be used by libwww for allocating
! 18: and de-allocating dynamic memory. As dynamic memory may be a scarce resource,
! 19: it is required that an application can handle memory exhaustion gracefully.
! 20: This module provides an interface that covers the following situations:
! 21: <P>
2.1 frystyk 22: <UL>
2.7 ! frystyk 23: <LI>
! 24: <A HREF="#Allocation">Handling of allocation, reallocation and de-allocation
! 25: of dynamic memory</A>
! 26: <LI>
! 27: <A HREF="#Memory">Recovering from temporary lack of available memory</A>
! 28: <LI>
! 29: <A HREF="#Panic">Panic handling in case a new allocation fails</A>
2.1 frystyk 30: </UL>
2.7 ! frystyk 31: <P>
! 32: <B>Note</B>: The Library <I>core</I> provides a default set of memory handlers
! 33: for allocating and de-allocating dynamic memory. In order to maintain a
! 34: reasonable performance, they are not registered dynamically but assigned
! 35: using <I>C style macros</I>. Hence, it is not possible to swap memory handler
! 36: at run time but this was considered to be a reasonable trade-off.
! 37: <P>
2.1 frystyk 38: This module is implemented by <A HREF="HTMemory.c">HTMemory.c</A>, and it
2.7 ! frystyk 39: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Reference
! 40: Library</A>.
2.1 frystyk 41: <PRE>
42: #ifndef HTMEMORY_H
43: #define HTMEMORY_H
44: </PRE>
2.7 ! frystyk 45: <H2>
! 46: <A NAME="Allocation">Allocation, Reallocation and De-allocation</A>
! 47: </H2>
! 48: <P>
! 49: The Library provides a default set of methods for handling dynamic memory.
! 50: They are very basic and essentially identical to the C style
! 51: <CODE>malloc</CODE>, <CODE>calloc</CODE>, <CODE>realloc</CODE>, and
! 52: <CODE>free</CODE>:
! 53: <PRE>extern void* HTMemory_malloc(size_t size);
2.1 frystyk 54: extern void* HTMemory_calloc(size_t count, size_t size);
55: extern void* HTMemory_realloc(void * ptr, size_t size);
56: extern void HTMemory_free(void* ptr);
57: </PRE>
2.7 ! frystyk 58: <H3>
! 59: Memory Macros
! 60: </H3>
! 61: <P>
! 62: The methods above are not referred directly in the Library. Instead we use
! 63: a set of C style macros. If you don't wany any memory management beyond normal
! 64: malloc and alloc then you can just use that instead of the HTMemory_* function.
! 65: You can of course also provide your own methods as well.
2.1 frystyk 66: <PRE>
2.2 frystyk 67: #ifndef __FILE__
68: #define __FILE__ ""
69: #endif
70:
71: #ifndef __LINE__
72: #define __LINE__ 0L
73: #endif
74:
2.1 frystyk 75: #define HT_MALLOC(size) HTMemory_malloc(size)
76: #define HT_CALLOC(count, size) HTMemory_calloc(count, size)
77: #define HT_REALLOC(ptr, size) HTMemory_realloc(ptr, size)
78: #define HT_FREE(pointer) {HTMemory_free(pointer);(pointer)=NULL;}
79: </PRE>
2.7 ! frystyk 80: <H2>
! 81: <A NAME="Memory">Memory Freer Functions</A>
! 82: </H2>
! 83: <P>
! 84: The dynamic memory freer functions are typically functions that are capable
! 85: of freeing large chunks of memory. In case a new allocation fails, the allocation
! 86: method looks for any registered freer functions to call. There can be multiple
! 87: freer functions and after each call, the allocation method tries again to
! 88: allocate the desired amount of dynamic memory. The freer functions are called
! 89: in <EM>reverse</EM> order meaning that the <EM>last</EM> one registered gets
! 90: called <EM>first</EM>. That way, it is easy to add temporary freer functions
2.1 frystyk 91: which then are guaranteed to be called first if a methods fails.
2.7 ! frystyk 92: <H3>
! 93: Add a Freer Function
! 94: </H3>
! 95: <P>
! 96: You can add a freer function by using the following method. The Library may
! 97: itself register a set of free functions during initialization. If the application
! 98: does not register any freer functions then the Library looks how it can free
! 99: internal memory. The freer function is passed the total number of
! 100: <I>bytes</I> requested by the allocation.
! 101: <PRE>typedef void HTMemoryCallback(size_t size);
2.1 frystyk 102:
103: extern BOOL HTMemoryCall_add (HTMemoryCallback * cbf);
104: </PRE>
2.7 ! frystyk 105: <H3>
! 106: Delete a Freer Function
! 107: </H3>
! 108: <P>
! 109: Freer functions can be deleted at any time in which case they are not called
! 110: anymore.
2.1 frystyk 111: <PRE>
112: extern BOOL HTMemoryCall_delete (HTMemoryCallback * cbf);
113: extern BOOL HTMemoryCall_deleteAll (void);
114: </PRE>
2.7 ! frystyk 115: <H2>
! 116: <A NAME="Panic">Panic Handling</A>
! 117: </H2>
! 118: <P>
! 119: If the freer functions are not capable of de-allocation enough memory then
! 120: the application must have an organized way of closing down. This is done
! 121: using the panic handler. In the libwww, each allocation is tested and
! 122: <CODE>HT_OUTOFMEM</CODE> is called if a <CODE>NULL</CODE> was returned.
! 123: <CODE>HT_OUTOFMEM</CODE> is a macro which by default calls
! 124: <CODE>HTMemory_outofmem()</CODE> but of course can point to any method. The
! 125: default handler calls an exit function defined by the application in a call
! 126: to <CODE>HTMemory_setExit()</CODE>. If the application has <I>not</I> defined
! 127: an exit function, <CODE>HTMemory_outofmem()</CODE> prints an error message
! 128: and calls <CODE>exit(1)</CODE>.
2.1 frystyk 129: <PRE>
2.2 frystyk 130: typedef void HTMemory_exitCallback(char *name, char *file, unsigned long line);
131:
132: extern void HTMemory_setExit(HTMemory_exitCallback * pExit);
133: extern HTMemory_exitCallback * HTMemory_exit(void);
134: </PRE>
2.7 ! frystyk 135: <H3>
! 136: Call the Exit Handler
! 137: </H3>
! 138: <P>
! 139: If an allocation fails then this function is called. If the application has
! 140: registered its own panic handler then this is called directly from this function.
! 141: Otherwise, the default behavior is to write a small message to stderr and
! 142: then exit.
2.2 frystyk 143: <PRE>
2.3 frystyk 144: #define outofmem(file, name) HT_OUTOFMEM(name)
145: #define HT_OUTOFMEM(name) HTMemory_outofmem((name), __FILE__, __LINE__)
2.2 frystyk 146:
2.1 frystyk 147: extern void HTMemory_outofmem(char * name, char * file, unsigned long line);
148: </PRE>
149: <PRE>
150: #endif /* HTMEMORY_H */
151: </PRE>
2.7 ! frystyk 152: <P>
! 153: <HR>
2.6 frystyk 154: <ADDRESS>
2.7 ! frystyk 155: @(#) $Id: HTMemory.html,v 2.6 1996/04/12 17:47:54 frystyk Exp $
2.6 frystyk 156: </ADDRESS>
2.7 ! frystyk 157: </BODY></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