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