1 /* 2 3 4 W3C Sample Code Library libwww Dynamic Memory Handlers 5 6 7 ! 8 Dynamic Memory Handlers 9 ! 10 */ 11 12 /* 13 ** (c) COPYRIGHT MIT 1995. 14 ** Please first read the full copyright statement in the file COPYRIGH. 15 */ 16 17 /* 18 19 This module defines any memory handler to be used by libwww for allocating 20 and de-allocating dynamic memory. As dynamic memory may be a scarce resource, 21 it is required that an application can handle memory exhaustion gracefully. 22 This module provides an interface that covers the following situations: 23 24 25 o 26 Handling of allocation, reallocation and de-allocation 27 of dynamic memory 28 o 29 Recovering from temporary lack of available memory 30 o 31 Panic handling in case a new allocation fails 32 33 34 Note: The Library core provides a default set of memory handlers 35 for allocating and de-allocating dynamic memory. In order to maintain a 36 reasonable performance, they are not registered dynamically but assigned 37 using C style macros. Hence, it is not possible to swap memory handler 38 at run time but this was considered to be a reasonable trade-off. 39 40 This module is implemented by HTMemory.c, and it 41 is a part of the W3C Sample Code 42 Library. 43 */ 44 45 #ifndef HTMEMORY_H 46 #define HTMEMORY_H 47 48 #include "HTUtils.h" 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /* 55 . 56 Allocation, Reallocation and De-allocation 57 . 58 59 The Library provides a default set of methods for handling dynamic memory. 60 They are very basic and essentially identical to the C style 61 malloc, calloc, realloc, and 62 free: 63 */ 64 extern void* HTMemory_malloc(size_t size); 65 extern void* HTMemory_calloc(size_t count, size_t size); 66 extern void* HTMemory_realloc(void * ptr, size_t size); 67 extern void HTMemory_free(void* ptr); 68 69 /* 70 ( 71 Memory Macros 72 ) 73 74 The methods above are not referred directly in the Library. Instead we use 75 a set of C style macros. If you don't wany any memory management beyond normal 76 malloc and alloc then you can just use that instead of the HTMemory_* function. 77 You can of course also provide your own methods as well. 78 */ 79 80 #define HT_MALLOC(size) HTMemory_malloc((size)) 81 #define HT_CALLOC(count, size) HTMemory_calloc((count), (size)) 82 #define HT_REALLOC(ptr, size) HTMemory_realloc((ptr), (size)) 83 #define HT_FREE(pointer) {HTMemory_free((pointer));((pointer))=NULL;} 84 85 /* 86 . 87 Memory Freer Functions 88 . 89 90 The dynamic memory freer functions are typically functions that are capable 91 of freeing large chunks of memory. In case a new allocation fails, the allocation 92 method looks for any registered freer functions to call. There can be multiple 93 freer functions and after each call, the allocation method tries again to 94 allocate the desired amount of dynamic memory. The freer functions are called 95 in reverse order meaning that the last one registered gets 96 called first. That way, it is easy to add temporary freer functions 97 which then are guaranteed to be called first if a methods fails. 98 ( 99 Add a Freer Function 100 ) 101 102 You can add a freer function by using the following method. The Library may 103 itself register a set of free functions during initialization. If the application 104 does not register any freer functions then the Library looks how it can free 105 internal memory. The freer function is passed the total number of 106 bytes requested by the allocation. 107 */ 108 typedef void HTMemoryCallback(size_t size); 109 110 extern BOOL HTMemoryCall_add (HTMemoryCallback * cbf); 111 112 /* 113 ( 114 Delete a Freer Function 115 ) 116 117 Freer functions can be deleted at any time in which case they are not called 118 anymore. 119 */ 120 121 extern BOOL HTMemoryCall_delete (HTMemoryCallback * cbf); 122 extern BOOL HTMemoryCall_deleteAll (void); 123 124 /* 125 . 126 Panic Handling 127 . 128 129 If the freer functions are not capable of de-allocation enough memory then 130 the application must have an organized way of closing down. This is done 131 using the panic handler. In the libwww, each allocation is tested and 132 HT_OUTOFMEM is called if a NULL was returned. 133 HT_OUTOFMEM is a macro which by default calls 134 HTMemory_outofmem() but of course can point to any method. The 135 default handler calls an exit function defined by the application in a call 136 to HTMemory_setExit(). If the application has not defined 137 an exit function, HTMemory_outofmem() prints an error message 138 and calls exit(1). 139 */ 140 141 typedef void HTMemory_exitCallback(char *name, char *file, unsigned long line); 142 143 extern void HTMemory_setExit(HTMemory_exitCallback * pExit); 144 extern HTMemory_exitCallback * HTMemory_exit(void); 145 146 /* 147 ( 148 Call the Exit Handler 149 ) 150 151 If an allocation fails then this function is called. If the application has 152 registered its own panic handler then this is called directly from this function. 153 Otherwise, the default behavior is to write a small message to stderr and 154 then exit. 155 */ 156 157 #define outofmem(file, name) HT_OUTOFMEM(name) 158 #define HT_OUTOFMEM(name) HTMemory_outofmem((name), __FILE__, __LINE__) 159 160 extern void HTMemory_outofmem(char * name, char * file, unsigned long line); 161 162 /* 163 */ 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif /* HTMEMORY_H */ 170 171 /* 172 173 174 175 @(#) $Id$ 176 177 */ 178