1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ 2 /* This Source Code Form is subject to the terms of the Mozilla Public 3 * License, v. 2.0. If a copy of the MPL was not distributed with this 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ 5 6 /* 7 ** File: prmem.h 8 ** Description: API to NSPR memory management functions 9 ** 10 */ 11 #ifndef prmem_h___ 12 #define prmem_h___ 13 14 #include "prtypes.h" 15 #include <stdlib.h> 16 17 PR_BEGIN_EXTERN_C 18 19 /* 20 ** Thread safe memory allocation. 21 ** 22 ** NOTE: pr wraps up malloc, free, calloc, realloc so they are already 23 ** thread safe (and are not declared here - look in stdlib.h). 24 */ 25 26 /* 27 ** PR_Malloc, PR_Calloc, PR_Realloc, and PR_Free have the same signatures 28 ** as their libc equivalent malloc, calloc, realloc, and free, and have 29 ** the same semantics. (Note that the argument type size_t is replaced 30 ** by PRUint32.) Memory allocated by PR_Malloc, PR_Calloc, or PR_Realloc 31 ** must be freed by PR_Free. 32 */ 33 34 NSPR_API(void *) PR_Malloc(PRUint32 size); 35 36 NSPR_API(void *) PR_Calloc(PRUint32 nelem, PRUint32 elsize); 37 38 NSPR_API(void *) PR_Realloc(void *ptr, PRUint32 size); 39 40 NSPR_API(void) PR_Free(void *ptr); 41 42 /* 43 ** The following are some convenience macros defined in terms of 44 ** PR_Malloc, PR_Calloc, PR_Realloc, and PR_Free. 45 */ 46 47 /*********************************************************************** 48 ** FUNCTION: PR_MALLOC() 49 ** DESCRIPTION: 50 ** PR_NEW() allocates an untyped item of size _size from the heap. 51 ** INPUTS: _size: size in bytes of item to be allocated 52 ** OUTPUTS: untyped pointer to the node allocated 53 ** RETURN: pointer to node or error returned from malloc(). 54 ***********************************************************************/ 55 #define PR_MALLOC(_bytes) (PR_Malloc((_bytes))) 56 57 /*********************************************************************** 58 ** FUNCTION: PR_NEW() 59 ** DESCRIPTION: 60 ** PR_NEW() allocates an item of type _struct from the heap. 61 ** INPUTS: _struct: a data type 62 ** OUTPUTS: pointer to _struct 63 ** RETURN: pointer to _struct or error returns from malloc(). 64 ***********************************************************************/ 65 #define PR_NEW(_struct) ((_struct *) PR_MALLOC(sizeof(_struct))) 66 67 /*********************************************************************** 68 ** FUNCTION: PR_REALLOC() 69 ** DESCRIPTION: 70 ** PR_REALLOC() re-allocates _ptr bytes from the heap as a _size 71 ** untyped item. 72 ** INPUTS: _ptr: pointer to node to reallocate 73 ** _size: size of node to allocate 74 ** OUTPUTS: pointer to node allocated 75 ** RETURN: pointer to node allocated 76 ***********************************************************************/ 77 #define PR_REALLOC(_ptr, _size) (PR_Realloc((_ptr), (_size))) 78 79 /*********************************************************************** 80 ** FUNCTION: PR_CALLOC() 81 ** DESCRIPTION: 82 ** PR_CALLOC() allocates a _size bytes untyped item from the heap 83 ** and sets the allocated memory to all 0x00. 84 ** INPUTS: _size: size of node to allocate 85 ** OUTPUTS: pointer to node allocated 86 ** RETURN: pointer to node allocated 87 ***********************************************************************/ 88 #define PR_CALLOC(_size) (PR_Calloc(1, (_size))) 89 90 /*********************************************************************** 91 ** FUNCTION: PR_NEWZAP() 92 ** DESCRIPTION: 93 ** PR_NEWZAP() allocates an item of type _struct from the heap 94 ** and sets the allocated memory to all 0x00. 95 ** INPUTS: _struct: a data type 96 ** OUTPUTS: pointer to _struct 97 ** RETURN: pointer to _struct 98 ***********************************************************************/ 99 #define PR_NEWZAP(_struct) ((_struct*)PR_Calloc(1, sizeof(_struct))) 100 101 /*********************************************************************** 102 ** FUNCTION: PR_DELETE() 103 ** DESCRIPTION: 104 ** PR_DELETE() unallocates an object previosly allocated via PR_NEW() 105 ** or PR_NEWZAP() to the heap. 106 ** INPUTS: pointer to previously allocated object 107 ** OUTPUTS: the referenced object is returned to the heap 108 ** RETURN: void 109 ***********************************************************************/ 110 #define PR_DELETE(_ptr) { PR_Free(_ptr); (_ptr) = NULL; } 111 112 /*********************************************************************** 113 ** FUNCTION: PR_FREEIF() 114 ** DESCRIPTION: 115 ** PR_FREEIF() conditionally unallocates an object previously allocated 116 ** vial PR_NEW() or PR_NEWZAP(). If the pointer to the object is 117 ** equal to zero (0), the object is not released. 118 ** INPUTS: pointer to previously allocated object 119 ** OUTPUTS: the referenced object is conditionally returned to the heap 120 ** RETURN: void 121 ***********************************************************************/ 122 #define PR_FREEIF(_ptr) if (_ptr) PR_DELETE(_ptr) 123 124 PR_END_EXTERN_C 125 126 #endif /* prmem_h___ */ 127