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