nsIMemory

nsIMemory is used to allocate and deallocate memory segments from a heap. The implementation is free to define the heap. NS_GetMemoryManager returns the global nsIMemory instance.

Method overview

Methods

Allocates a block of memory of a particular size.

voidPtr alloc(
  in size_t size
);

Parameters

size

The size of the block to allocate.

Return value

If the memory cannot be allocated (because of an out-of-memory condition), null is returned. Otherwise, it returns a pointer to the newly allocated memory segment. The result must be freed with a call to free() when it is no longer needed.

Frees a previously allocated block of memory.

void free(
  in voidPtr ptr
);

Parameters

ptr

The address of the memory block to free. This may be null, in which case nothing happens.

heapMinimize()

Attempts to shrink the size of the heap. A particular nsIMemory instance may choose not to implement this method.

void heapMinimize(
  in boolean immediate
);

Parameters

immediate

If true, heap minimization will occur immediately if the call was made on the main thread. If false, the flush will be scheduled to happen when the app is idle.

Determine if we are in a low-memory situation (what constitutes low-memory is platform dependent). This can be used to trigger the memory pressure observers.

boolean isLowMemory();

Parameters

None.

Return value

true if we are in a low-memory situation. Otherwise false.

realloc()

Reallocates a block of memory to a new size.

voidPtr realloc(
  in voidPtr ptr,
  in size_t newSize
);

Parameters

ptr

The address of the memory block to reallocate. This may be null, in which case realloc behaves like alloc().

newSize

Specifies the new size in bytes of the block of memory to allocate. This may be 0, in which case realloc behaves like alloc().

Return value

null if the memory allocation fails. Otherwise, it returns a pointer to the newly allocated memory segment. The result must be freed with a call to free() when it is no longer needed.

Low memory notifications

An nsIMemory implementation may be capable of monitoring heap usage. Moreover, a mechanism exists by which a client can receive notifications about 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 notifications that can occur. These types will be passed as the aData parameter of the of the "memory-pressure" notification:

"low-memory"

This will be passed as the value of aData when a low-memory condition occurs (not necessarily an out-of-memory condition).

"heap-minimize"

This will be passed as the value of aData when an explicit call to heapMinimize() was made.

"alloc-failure"

This will be passed as the value of aData when an out-of-memory condition occurs.

When a nsIMemory instance notifies memory pressure observers, it passes itself as the aSubject parameter in the call to nsIObserverService.notifyObservers(). This allows nsIObserver implementations to observe multiple nsIMemory instances and determine the source of memory pressure notifications.

Remarks

This interface was frozen for Gecko 0.9.6. See bug 99151 for details. From Gecko 2.0 interfaces are no longer frozen.

See also

• NS_GetMemoryManager
• nsIObserverService.notifyObservers()
• nsIObserver
• nsIObserverService