You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

TOC PREV NEXT INDEX

Embedding Gecko API

nsIMemory

This interface is used to allocate and deallocate memory. It also provides for notifications in low-memory situations.

A client that wishes to be notified of low memory situations (for example, because the client maintains a large memory cache that could be released when memory is tight) should register with the observer service (see nsIObserverService ) using the topic memory-pressure. There are three specific types of notications that can occur. These types will be passed as the aData parameter of the "memory-pressure" notification:

low-memory: This will be passed as the extra data when the pressure observer is being asked to flush for low-memory conditions.
heap-minimize: This will be passed as the extra data when the pressure observer is being asked to flush because of a heap minimize call.
alloc-failure: This will be passed as the extra data when the pressure observer has been asked to flush because a malloc or realloc has failed.

This interface is partially scriptable.

Methods
alloc

Allocates a block of memory of a particular size. If the memory cannot be allocated (because of an out-of-memory condition), null is returned. This method is not scriptable.

Syntax: 

voidPtr nsIMemory::alloc(in size_t size)

Parameters:

size: The size of the block to allocate.

Returns:

The block of memory.
realloc

Reallocates a block of memory to a new size. This method is not scriptable.

Syntax: 

voidPtr nsIMemory::realloc(in voidPtr ptr,
	in size_t newSize)

Parameters:

ptr: The block of memory to reallocate.
size: The new size.

Returns:

The reallocated block of memory

Note: If ptr is null, this function behaves like malloc. If s is the size of the block to which ptr points, the first min(s, size) bytes of ptr's block are copied to the new block. If the allocation succeeds, ptr is freed and a pointer to the new block returned. If the allocation fails, ptr is not freed and null is returned. The returned value may be the same as ptr.

free

Frees a block of memory. Null is a permissible value, in which case nothing happens. This method is not scriptable.

Syntax: 

void nsIMemory::free(in voidPtr ptr)

Parameters:

ptr: The block of memory to free.

Returns:

None.
heapMinimize

Attempts to shrink the heap. This method is scriptable.

Syntax: 

void nsIMemory::heapMinimize(in boolean immediate)

Parameters:

immediate: If the value is TRUE, heap minimization will occur immediately if the call was made on the main thread. If the value is FALSE, the flush will be scheduled to happen when the app is idle.

nsresult:

NS_ERROR_FAILURE if 'immediate' is set and the call was not on the application's main thread.
isLowMemory

Indicates a low-memory situation (what constitutes low-memory is platform dependent). This can be used to trigger the memory pressure observers.

Syntax: 

boolean nsIMemory::isLowMemory()

Parameters:

None.

Returns:

TRUE if memory is low.
FALSE otherwise.
Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX