Annotation of libwww/Library/src/HTMemory.html, revision 2.10
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.10 ! frystyk 39: is a part of the <A HREF="http://www.w3.org/pub/WWW/Library/">W3C Sample Code
2.7 frystyk 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.8 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;}
2.1 frystyk 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
2.9 frystyk 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.10 ! frystyk 155: @(#) $Id: HTMemory.html,v 2.9 1996/10/10 22:35:14 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