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