Annotation of libwww/Library/src/HTMemory.html, revision 2.13
2.1 frystyk 1: <HTML>
2: <HEAD>
2.9 frystyk 3: <!-- Changed by: Henrik Frystyk Nielsen, 23-Jun-1996 -->
2.10 frystyk 4: <TITLE>W3C Sample Code 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.12 frystyk 39: is a part of the <A HREF="http://www.w3.org/Library/">W3C Sample Code
2.7 frystyk 40: Library</A>.
2.1 frystyk 41: <PRE>
42: #ifndef HTMEMORY_H
43: #define HTMEMORY_H
2.11 frystyk 44:
45: #include "<A HREF="HTUtils.html">HTUtils.h</A>"
2.13 ! vbancrof 46:
! 47: #ifdef __cplusplus
! 48: extern "C" {
! 49: #endif
2.1 frystyk 50: </PRE>
2.7 frystyk 51: <H2>
52: <A NAME="Allocation">Allocation, Reallocation and De-allocation</A>
53: </H2>
54: <P>
55: The Library provides a default set of methods for handling dynamic memory.
56: They are very basic and essentially identical to the C style
57: <CODE>malloc</CODE>, <CODE>calloc</CODE>, <CODE>realloc</CODE>, and
58: <CODE>free</CODE>:
59: <PRE>extern void* HTMemory_malloc(size_t size);
2.1 frystyk 60: extern void* HTMemory_calloc(size_t count, size_t size);
61: extern void* HTMemory_realloc(void * ptr, size_t size);
62: extern void HTMemory_free(void* ptr);
63: </PRE>
2.7 frystyk 64: <H3>
65: Memory Macros
66: </H3>
67: <P>
68: The methods above are not referred directly in the Library. Instead we use
69: a set of C style macros. If you don't wany any memory management beyond normal
70: malloc and alloc then you can just use that instead of the HTMemory_* function.
71: You can of course also provide your own methods as well.
2.1 frystyk 72: <PRE>
2.8 frystyk 73: #define HT_MALLOC(size) HTMemory_malloc((size))
74: #define HT_CALLOC(count, size) HTMemory_calloc((count), (size))
75: #define HT_REALLOC(ptr, size) HTMemory_realloc((ptr), (size))
76: #define HT_FREE(pointer) {HTMemory_free((pointer));((pointer))=NULL;}
2.1 frystyk 77: </PRE>
2.7 frystyk 78: <H2>
79: <A NAME="Memory">Memory Freer Functions</A>
80: </H2>
81: <P>
82: The dynamic memory freer functions are typically functions that are capable
83: of freeing large chunks of memory. In case a new allocation fails, the allocation
84: method looks for any registered freer functions to call. There can be multiple
85: freer functions and after each call, the allocation method tries again to
86: allocate the desired amount of dynamic memory. The freer functions are called
87: in <EM>reverse</EM> order meaning that the <EM>last</EM> one registered gets
88: called <EM>first</EM>. That way, it is easy to add temporary freer functions
2.1 frystyk 89: which then are guaranteed to be called first if a methods fails.
2.7 frystyk 90: <H3>
91: Add a Freer Function
92: </H3>
93: <P>
94: You can add a freer function by using the following method. The Library may
95: itself register a set of free functions during initialization. If the application
96: does not register any freer functions then the Library looks how it can free
97: internal memory. The freer function is passed the total number of
98: <I>bytes</I> requested by the allocation.
99: <PRE>typedef void HTMemoryCallback(size_t size);
2.1 frystyk 100:
101: extern BOOL HTMemoryCall_add (HTMemoryCallback * cbf);
102: </PRE>
2.7 frystyk 103: <H3>
104: Delete a Freer Function
105: </H3>
106: <P>
107: Freer functions can be deleted at any time in which case they are not called
108: anymore.
2.1 frystyk 109: <PRE>
110: extern BOOL HTMemoryCall_delete (HTMemoryCallback * cbf);
111: extern BOOL HTMemoryCall_deleteAll (void);
112: </PRE>
2.7 frystyk 113: <H2>
114: <A NAME="Panic">Panic Handling</A>
115: </H2>
116: <P>
117: If the freer functions are not capable of de-allocation enough memory then
118: the application must have an organized way of closing down. This is done
119: using the panic handler. In the libwww, each allocation is tested and
120: <CODE>HT_OUTOFMEM</CODE> is called if a <CODE>NULL</CODE> was returned.
121: <CODE>HT_OUTOFMEM</CODE> is a macro which by default calls
122: <CODE>HTMemory_outofmem()</CODE> but of course can point to any method. The
123: default handler calls an exit function defined by the application in a call
124: to <CODE>HTMemory_setExit()</CODE>. If the application has <I>not</I> defined
125: an exit function, <CODE>HTMemory_outofmem()</CODE> prints an error message
126: and calls <CODE>exit(1)</CODE>.
2.1 frystyk 127: <PRE>
2.2 frystyk 128: typedef void HTMemory_exitCallback(char *name, char *file, unsigned long line);
129:
130: extern void HTMemory_setExit(HTMemory_exitCallback * pExit);
131: extern HTMemory_exitCallback * HTMemory_exit(void);
132: </PRE>
2.7 frystyk 133: <H3>
134: Call the Exit Handler
135: </H3>
136: <P>
137: If an allocation fails then this function is called. If the application has
138: registered its own panic handler then this is called directly from this function.
139: Otherwise, the default behavior is to write a small message to stderr and
2.9 frystyk 140: then exit.
2.2 frystyk 141: <PRE>
2.3 frystyk 142: #define outofmem(file, name) HT_OUTOFMEM(name)
143: #define HT_OUTOFMEM(name) HTMemory_outofmem((name), __FILE__, __LINE__)
2.2 frystyk 144:
2.1 frystyk 145: extern void HTMemory_outofmem(char * name, char * file, unsigned long line);
146: </PRE>
147: <PRE>
2.13 ! vbancrof 148: #ifdef __cplusplus
! 149: }
! 150: #endif
! 151:
2.1 frystyk 152: #endif /* HTMEMORY_H */
153: </PRE>
2.7 frystyk 154: <P>
155: <HR>
2.6 frystyk 156: <ADDRESS>
2.13 ! vbancrof 157: @(#) $Id: HTMemory.html,v 2.12 1998/05/14 02:10:45 frystyk Exp $
2.6 frystyk 158: </ADDRESS>
2.7 frystyk 159: </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