Choosing the right memory allocator

There are a lot of different memory allocators in the Mozilla source tree. This article looks over some of them and tries to sort out which should be used under what circumstances.

Allocating memory in XPCOM

These are general purpose memory-management routines that you should use unless your code falls into one of the other categories below. Use these if you link against XPCOM or XPCOM Glue; this includes extensions with binary components. See the XPCOM string guide for additional information.

NS_Alloc() == nsIMemory::alloc()
NS_Realloc() == nsIMemory::realloc()
NS_Free() == nsIMemory::free()
nsMemory::Clone() (note: not part of nsIMemory)

See Infallible memory allocation for information about how to allocate memory infallibly; that is, how to use memory allocators that will only return valid memory buffers, and never return null.

Allocating strings in XPCOM code

See "Callee-allocated Parameters" in the XPCOM Strings guide; use ToNewCString() or ToNewUnicode() to allocate strings that will be passed out. These methods convert ns*String to nsIMemory allocated, unowned [PRUni]char* buffers.

Do not use nsCRT::strdup for returning values from an XPCOM object, as that uses a different allocator.

NSPR memory allocators

You should only use the NSPR allocators within NSPR or the security code located in the <tt>/security/</tt> subtree of the source code. Avoid using them elsewhere.

PR_Alloc() (do not use, no users and only exists in <tt>/security/</tt>; use PR_Malloc() instead)
PR_Malloc() == PR_MALLOC
PR_Calloc() == PR_CALLOC
PR_Realloc() == PR_REALLOC
PR_Free()
PR_NEW (pass in a struct to allocate its size)
PR_NEWZAP (same as PR_NEW, but zeros memory)
PR_DELETE (PR_Free() and also clears the pointer)
PR_FREEIF

Special cases

PR_smprintf(), PR_sprintf_append(), PR_vsmprintf() and PR_vsprintf_append() must be freed with PR_smprintf_free()
PL_strdup(), PL_strndup() must be freed with PL_strfree()
nsCRT::strdup/nsCRT::strndup must be freed with nsCRT::free

Allocating memory within plugins

There are special memory allocation routines specifically intended for use from plugins, which must not be used from within Mozilla itself. See Gecko Plugin API Reference:Memory.

JavaScript API memory allocators

There are also routines intended for use within the JavaScript runtime engine (SpiderMonkey). This is the /js/ subtree of the source code. Also, all consumers of the JSAPI must use these routines for allocating memory they plan to pass to the JavaScript runtime. See JSAPI Reference for further information.

Arena allocators

NSPR exposes arena allocators that can be used to efficiently allocate lots of small, uniformly sized objects.

PresShell arena

nsIPresShell::AllocateFrame() and nsPresContext::AllocateFromShell() can be used to allocate memory from an arena maintained by the PresShell. These should only be used to allocate objects that are guaranteed to have a shorter lifetime than the PresShell in question (typically layout data structures), because the PresShell destructor will wipe out the arena, leaving any pointers to memory allocated from it dangling.

The corresponding deallocators are nsIPresShell::FreeFrame() and nsPresContext::FreeToShell().

Notes

Memory that is allocated with the C standard library (malloc() and free()) should not be passed between shared libraries. These memory buffers may be used within a single shared library or program. For data structures being passed across XPCOM boundaries, use NS_Alloc() instead.