home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / libpics / htmemory.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  7.1 KB  |  181 lines
  1.  
  2. /*  W3 Copyright statement 
  3. Copyright 1995 by: Massachusetts Institute of Technology (MIT), INRIA</H2>
  4.  
  5. This W3C software is being provided by the copyright holders under the
  6. following license. By obtaining, using and/or copying this software,
  7. you agree that you have read, understood, and will comply with the
  8. following terms and conditions: 
  9.  
  10. Permission to use, copy, modify, and distribute this software and its
  11. documentation for any purpose and without fee or royalty is hereby
  12. granted, provided that the full text of this NOTICE appears on
  13. <EM>ALL</EM> copies of the software and documentation or portions
  14. thereof, including modifications, that you make. 
  15.  
  16. <B>THIS SOFTWARE IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
  17. REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
  18. BUT NOT LIMITATION, COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR
  19. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR
  20. THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY
  21. THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
  22. COPYRIGHT HOLDERS WILL BEAR NO LIABILITY FOR ANY USE OF THIS SOFTWARE
  23. OR DOCUMENTATION.
  24.  
  25. The name and trademarks of copyright holders may NOT be used
  26. in advertising or publicity pertaining to the software without
  27. specific, written prior permission.  Title to copyright in this
  28. software and any associated documentation will at all times remain
  29. with copyright holders. 
  30. */
  31. /*                                       W3C Reference Library libwww Dynamic Memory Handlers
  32.                                  DYNAMIC MEMORY HANDLERS
  33.                                              
  34.  */
  35. /*
  36. **      (c) COPYRIGHT MIT 1995.
  37. **      Please first read the full copyright statement in the file COPYRIGH.
  38. */
  39. /*
  40.  
  41.    This module defines any memory handler to be used by libwww for allocating and
  42.    de-allocating dynamic memory. As dynamic memory may be a scarce resource, it is
  43.    required that an application can handle memory exhaustion gracefully. This module
  44.    provides an interface that covers the following situations:
  45.    
  46.       Handling of allocation, reallocation and de-allocation of dynamic memory
  47.       
  48.       Recovering from temporary lack of available memory
  49.       
  50.       Panic handling in case a new allocation fails
  51.       
  52.    _Note_: The Library _core_ provides a default set of memory handlers for allocating and
  53.    de-allocating dynamic memory. In order to maintain a reasonable performance, they are
  54.    not registered dynamically but assigned using _C style macros_. Hence, it is not
  55.    possible to swap memory handler at run time but this was considered to be a reasonable
  56.    trade-off.
  57.    
  58.    This module is implemented by HTMemory.c, and it is a part of the W3C Reference
  59.    Library.
  60.    
  61.  */
  62. #ifndef HTMEMORY_H
  63. #define HTMEMORY_H
  64. /*
  65.  
  66. ALLOCATION, REALLOCATION AND DE-ALLOCATION
  67.  
  68.    The Library provides a default set of methods for handling dynamic memory. They are
  69.    very basic and essentially identical to the C style malloc, calloc, realloc, and free:
  70.    
  71.  */
  72.  
  73. /* --- BEGIN added by mharmsen@netscape.com on 7/10/97 --- */
  74. #ifndef BOOL
  75. #define BOOL char
  76. #endif
  77. /* --- END added by mharmsen@netscape.com on 7/10/97 --- */
  78.  
  79. extern void* HTMemory_malloc(size_t size);
  80. extern void* HTMemory_calloc(size_t count, size_t size);
  81. extern void* HTMemory_realloc(void * ptr, size_t size);
  82. extern void HTMemory_free(void* ptr);
  83.  
  84. /*
  85.  
  86.   Memory Macros
  87.   
  88.    The methods above are not referred directly in the Library. Instead we use a set of C
  89.    style macros. If you don't wany any memory management beyond normal malloc and alloc
  90.    then you can just use that instead of the HTMemory_* function. You can of course also
  91.    provide your own methods as well.
  92.    
  93.  */
  94. #ifndef __FILE__
  95. #define __FILE__ ""
  96. #endif
  97.  
  98. #ifndef __LINE__
  99. #define __LINE__ 0L
  100. #endif
  101.  
  102. #define HT_MALLOC(size)         HTMemory_malloc((size))
  103. #define HT_CALLOC(count, size)  HTMemory_calloc((count), (size))
  104. #define HT_REALLOC(ptr, size)   HTMemory_realloc((ptr), (size))
  105. #define HT_FREE(pointer)        {HTMemory_free((pointer));((pointer))=NULL;}
  106. /*
  107.  
  108. MEMORY FREER FUNCTIONS
  109.  
  110.    The dynamic memory freer functions are typically functions that are capable of freeing
  111.    large chunks of memory. In case a new allocation fails, the allocation method looks for
  112.    any registered freer functions to call. There can be multiple freer functions and after
  113.    each call, the allocation method tries again to allocate the desired amount of dynamic
  114.    memory. The freer functions are called in reverseorder meaning that the lastone
  115.    registered gets called first. That way, it is easy to add temporary freer functions
  116.    which then are guaranteed to be called first if a methods fails.
  117.    
  118.   Add a Freer Function
  119.   
  120.    You can add a freer function by using the following method. The Library may itself
  121.    register a set of free functions during initialization. If the application does not
  122.    register any freer functions then the Library looks how it can free internal memory.
  123.    The freer function is passed the total number of _bytes_ requested by the allocation.
  124.    
  125.  */
  126. typedef void (*HTMemoryCallback());  /* jhines -- 7/9/97 */
  127. /* typedef void HTMemoryCallback(size_t size); */
  128.  
  129. extern BOOL HTMemoryCall_add (HTMemoryCallback * cbf);
  130. /*
  131.  
  132.   Delete a Freer Function
  133.   
  134.    Freer functions can be deleted at any time in which case they are not called anymore.
  135.    
  136.  */
  137. extern BOOL HTMemoryCall_delete (HTMemoryCallback * cbf);
  138. extern BOOL HTMemoryCall_deleteAll (void);
  139. /*
  140.  
  141. PANIC HANDLING
  142.  
  143.    If the freer functions are not capable of de-allocation enough memory then the
  144.    application must have an organized way of closing down. This is done using the panic
  145.    handler. In the libwww, each allocation is tested and HT_OUTOFMEMis called if a NULLwas
  146.    returned. HT_OUTOFMEMis a macro which by default calls HTMemory_outofmem()but of course
  147.    can point to any method. The default handler calls an exit function defined by the
  148.    application in a call to HTMemory_setExit(). If the application has _not_ defined an
  149.    exit function, HTMemory_outofmem()prints an error message and calls exit(1).
  150.    
  151.  */
  152. typedef void HTMemory_exitCallback(char *name, char *file, unsigned long line);
  153.  
  154. extern void HTMemory_setExit(HTMemory_exitCallback * pExit);
  155. extern HTMemory_exitCallback * HTMemory_exit(void);
  156. /*
  157.  
  158.   Call the Exit Handler
  159.   
  160.    If an allocation fails then this function is called. If the application has registered
  161.    its own panic handler then this is called directly from this function. Otherwise, the
  162.    default behavior is to write a small message to stderr and then exit.
  163.    
  164.  */
  165. #define outofmem(file, name)    HT_OUTOFMEM(name)
  166. #define HT_OUTOFMEM(name)       HTMemory_outofmem((name), __FILE__, __LINE__)
  167.  
  168. extern void HTMemory_outofmem(char * name, char * file, unsigned long line);
  169. /*
  170.  
  171.  */
  172. #endif /* HTMEMORY_H */
  173. /*
  174.  
  175.    
  176.    ___________________________________
  177.    
  178.                            @(#) $Id: htmemory.h,v 3.1 1998/03/28 03:32:07 ltabb Exp $
  179.                                                                                           
  180.     */
  181.