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