Infallible memory allocation

  • Revision slug: Infallible_memory_allocation
  • Revision title: Infallible memory allocation
  • Revision id: 77913
  • Created:
  • Creator: cgj
  • Is current revision? No
  • Comment 4 words added

Revision Content

{{ gecko_minversion_header("2.0") }}

There's ongoing work to implement infallible memory allocators. These are memory allocation routines that never return null; that is, they always successfully return the requested block of memory. This is in contrast to a traditional, fallible, memory allocator that can return null indicating that the request failed.

Currently, while code is transitioned to be compatible with infallible memory allocators, you have to explicitly decide whether to use infallible allocation or not. Eventually, however, the generic memory allocators (malloc() and NS_Alloc()) will become infallible.

How can memory allocation be infallible?

The term "infallible" means that your memory allocation request is guaranteed to succeed: your code can never see a failed request, and so doesn't need to check for failure.

Inside the allocation routine, the situation is different. Under extreme memory conditions, it's possible that the allocation will fail; however, the allocation routine will not, in this scenario, return to your code. Instead, the application will terminate. This should be rare, because the memory management system will do everything it can to find the memory you've asked for.

Choosing a memory allocator

As you write new code that needs to allocate memory, there are some simple rules to follow to help you decide whether to use a fallible or an infallible memory allocator:

  • If you're allocating what may be a large chunk of memory, you should allocate the memory fallibly (using moz_malloc() for example), and check the result to be sure it's not null. You should do this for large memory allocations because in extremely low memory conditions, as described in How can memory allocation be infallible?, the application may terminate if an infallible allocator can't find the memory you requested.
  • If you don't know whether or not the memory will be large, use the standard malloc() routine, which is currently fallible but will eventually become infallible. Be sure to check the result for null.
  • When instantiating objects, the new operator creates them infallibly by default. If you want to allocate them fallibly, use the syntax new (fallible_t()) Foo().
  • When in doubt, use the infallible allocator and don't null check.

Explicitly infallible memory allocators

The following memory allocators are explicitly infallible, and will remain so; they are guaranteed to return a valid memory pointer.

p = moz_xmalloc();
p = moz_xrealloc(); 
f = new Foo();
fArray = new Foo[];
n = ::operator new(...);
nArray = ::operator new[](...);

Explicitly fallible memory allocators

These memory allocators are explicitly fallible, and will remain so. When using these, you must check to ensure the resulting value isn't null before attempting to use the returned memory.

p = moz_malloc();
p = moz_realloc(); 
namespace mozilla {
  f = new (fallible_t()) Foo();
  fArray = new (fallible_t()) Foo[];
}
namespace mozilla {
  n = ::operator new(fallible_t(), ...);
  nArray = ::operator new[](fallible_t(), ...);
}

Eventually infallible memory allocators

The following memory allocators are currently fallible, but will become infallible in the relatively near future:

p = malloc();
p = NS_Alloc(); 

See also

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>There's ongoing work to implement <strong>infallible memory allocators</strong>. These are memory allocation routines that never return <code>null</code>; that is, they always successfully return the requested block of memory. This is in contrast to a traditional, fallible, memory allocator that can return <code>null</code> indicating that the request failed.</p>
<p>Currently, while code is transitioned to be compatible with infallible memory allocators, you have to explicitly decide whether to use infallible allocation or not. Eventually, however, the generic memory allocators (<code>malloc()</code> and <code>NS_Alloc()</code>) will become infallible.</p>
<h2>How can memory allocation be infallible?</h2>
<p>The term "infallible" means that your memory allocation request is guaranteed to succeed: your code can never see a failed request, and so doesn't need to check for failure.</p>
<p>Inside the allocation routine, the situation is different. Under extreme memory conditions, it's possible that the allocation will fail; however, the allocation routine will not, in this scenario, return to your code. Instead, the application will terminate. This should be rare, because the memory management system will do everything it can to find the memory you've asked for.</p>
<h2>Choosing a memory allocator</h2>
<p>As you write new code that needs to allocate memory, there are some simple rules to follow to help you decide whether to use a fallible or an infallible memory allocator:</p>
<ul> <li>If you're allocating what may be a large chunk of memory, you should allocate the memory fallibly (using <code>moz_malloc()</code> for example), and check the result to be sure it's not <code>null</code>. You should do this for large memory allocations because in extremely low memory conditions, as described in <a href="/en/Infallible_memory_allocation#How_can_memory_allocation_be_infallible.3f" title="en/Infallible memory allocation#How can memory allocation be infallible.3f">How can memory allocation be infallible?</a>, the application may terminate if an infallible allocator can't find the memory you requested.</li> <li>If you don't know whether or not the memory will be large, use the standard <code>malloc()</code> routine, which is currently fallible but will eventually become infallible. Be sure to check the result for <code>null</code>.</li> <li>When instantiating objects, the <code>new</code> operator creates them infallibly by default. If you want to allocate them fallibly, use the syntax <code>new (fallible_t()) Foo()</code>.</li> <li>When in doubt, use the infallible allocator and don't <code>null</code> check.</li>
</ul>
<h2>Explicitly infallible memory allocators</h2>
<p>The following memory allocators are explicitly infallible, and will remain so; they are guaranteed to return a valid memory pointer.</p>
<pre>p = moz_xmalloc();
p = moz_xrealloc(); 
</pre>
<pre>f = new Foo();
fArray = new Foo[];
</pre>
<pre>n = ::operator new(...);
nArray = ::operator new[](...);
</pre><h2>Explicitly fallible memory allocators</h2>
<p>These memory allocators are explicitly fallible, and will remain so. When using these, you must check to ensure the resulting value isn't <code>null</code> before attempting to use the returned memory.</p>
<pre>p = moz_malloc();
p = moz_realloc(); 
</pre>
<pre>namespace mozilla {
  f = new (fallible_t()) Foo();
  fArray = new (fallible_t()) Foo[];
}
</pre>
<pre>namespace mozilla {
  n = ::operator new(fallible_t(), ...);
  nArray = ::operator new[](fallible_t(), ...);
}
</pre><h2>Eventually infallible memory allocators</h2>
<p>The following memory allocators are currently fallible, but will become infallible in the relatively near future:</p>
<pre>p = malloc();
p = NS_Alloc(); 
</pre>
<h2>See also</h2>
<ul> <li><a href="/en/Choosing_the_right_memory_allocator" title="en/Choosing the right memory allocator">Choosing the right memory allocator</a></li> <li><a href="/en/NS_Alloc" title="en/NS Alloc"><code>NS_Alloc()</code></a></li>
</ul>
Revert to this revision