Back to index

lightning-sunbird  0.9+nobinonly
prmem.h
Go to the documentation of this file.
00001 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is the Netscape Portable Runtime (NSPR).
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998-2000
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either the GNU General Public License Version 2 or later (the "GPL"), or
00026  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 /*
00039 ** File: prmem.h
00040 ** Description: API to NSPR memory management functions
00041 **
00042 */
00043 #ifndef prmem_h___
00044 #define prmem_h___
00045 
00046 #include "prtypes.h"
00047 #include <stdlib.h>
00048 
00049 PR_BEGIN_EXTERN_C
00050 
00051 /*
00052 ** Thread safe memory allocation.
00053 **
00054 ** NOTE: pr wraps up malloc, free, calloc, realloc so they are already
00055 ** thread safe (and are not declared here - look in stdlib.h).
00056 */
00057 
00058 /*
00059 ** PR_Malloc, PR_Calloc, PR_Realloc, and PR_Free have the same signatures
00060 ** as their libc equivalent malloc, calloc, realloc, and free, and have
00061 ** the same semantics.  (Note that the argument type size_t is replaced
00062 ** by PRUint32.)  Memory allocated by PR_Malloc, PR_Calloc, or PR_Realloc
00063 ** must be freed by PR_Free.
00064 */
00065 
00066 NSPR_API(void *) PR_Malloc(PRUint32 size);
00067 
00068 NSPR_API(void *) PR_Calloc(PRUint32 nelem, PRUint32 elsize);
00069 
00070 NSPR_API(void *) PR_Realloc(void *ptr, PRUint32 size);
00071 
00072 NSPR_API(void) PR_Free(void *ptr);
00073 
00074 /*
00075 ** The following are some convenience macros defined in terms of
00076 ** PR_Malloc, PR_Calloc, PR_Realloc, and PR_Free.
00077 */
00078 
00079 /***********************************************************************
00080 ** FUNCTION:  PR_MALLOC()
00081 ** DESCRIPTION:
00082 **   PR_NEW() allocates an untyped item of size _size from the heap.
00083 ** INPUTS:  _size: size in bytes of item to be allocated
00084 ** OUTPUTS:   untyped pointer to the node allocated
00085 ** RETURN:    pointer to node or error returned from malloc().
00086 ***********************************************************************/
00087 #define PR_MALLOC(_bytes) (PR_Malloc((_bytes)))
00088 
00089 /***********************************************************************
00090 ** FUNCTION:  PR_NEW()
00091 ** DESCRIPTION:
00092 **   PR_NEW() allocates an item of type _struct from the heap.
00093 ** INPUTS:  _struct: a data type
00094 ** OUTPUTS:   pointer to _struct
00095 ** RETURN:    pointer to _struct or error returns from malloc().
00096 ***********************************************************************/
00097 #define PR_NEW(_struct) ((_struct *) PR_MALLOC(sizeof(_struct)))
00098 
00099 /***********************************************************************
00100 ** FUNCTION:  PR_REALLOC()
00101 ** DESCRIPTION:
00102 **   PR_REALLOC() re-allocates _ptr bytes from the heap as a _size
00103 **   untyped item.
00104 ** INPUTS:    _ptr: pointer to node to reallocate
00105 **          _size: size of node to allocate
00106 ** OUTPUTS:   pointer to node allocated
00107 ** RETURN:    pointer to node allocated
00108 ***********************************************************************/
00109 #define PR_REALLOC(_ptr, _size) (PR_Realloc((_ptr), (_size)))
00110 
00111 /***********************************************************************
00112 ** FUNCTION:  PR_CALLOC()
00113 ** DESCRIPTION:
00114 **   PR_CALLOC() allocates a _size bytes untyped item from the heap
00115 **   and sets the allocated memory to all 0x00.
00116 ** INPUTS:    _size: size of node to allocate
00117 ** OUTPUTS:   pointer to node allocated
00118 ** RETURN:    pointer to node allocated
00119 ***********************************************************************/
00120 #define PR_CALLOC(_size) (PR_Calloc(1, (_size)))
00121 
00122 /***********************************************************************
00123 ** FUNCTION:  PR_NEWZAP()
00124 ** DESCRIPTION:
00125 **   PR_NEWZAP() allocates an item of type _struct from the heap
00126 **   and sets the allocated memory to all 0x00.
00127 ** INPUTS:    _struct: a data type
00128 ** OUTPUTS:   pointer to _struct
00129 ** RETURN:    pointer to _struct
00130 ***********************************************************************/
00131 #define PR_NEWZAP(_struct) ((_struct*)PR_Calloc(1, sizeof(_struct)))
00132 
00133 /***********************************************************************
00134 ** FUNCTION:  PR_DELETE()
00135 ** DESCRIPTION:
00136 **   PR_DELETE() unallocates an object previosly allocated via PR_NEW()
00137 **   or PR_NEWZAP() to the heap.
00138 ** INPUTS:    pointer to previously allocated object
00139 ** OUTPUTS:   the referenced object is returned to the heap
00140 ** RETURN:    void
00141 ***********************************************************************/
00142 #define PR_DELETE(_ptr) { PR_Free(_ptr); (_ptr) = NULL; }
00143 
00144 /***********************************************************************
00145 ** FUNCTION:  PR_FREEIF()
00146 ** DESCRIPTION:
00147 **   PR_FREEIF() conditionally unallocates an object previously allocated
00148 **   vial PR_NEW() or PR_NEWZAP(). If the pointer to the object is
00149 **   equal to zero (0), the object is not released.
00150 ** INPUTS:    pointer to previously allocated object
00151 ** OUTPUTS:   the referenced object is conditionally returned to the heap
00152 ** RETURN:    void
00153 ***********************************************************************/
00154 #define PR_FREEIF(_ptr)     if (_ptr) PR_DELETE(_ptr)
00155 
00156 PR_END_EXTERN_C
00157 
00158 #endif /* prmem_h___ */