xpcom/base/nsIMemory.idlScriptable
This interface represents a generic memory allocator.
Inherits from: nsISupports Last changed in Gecko 0.9.6

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

voidPtr alloc(in size_t size); Violates the XPCOM interface guidelines
void free(in voidPtr ptr); Violates the XPCOM interface guidelines
void heapMinimize(in boolean immediate);
boolean isLowMemory(); Deprecated since Gecko 2.0
voidPtr realloc(in voidPtr ptr, in size_t newSize); Violates the XPCOM interface guidelines

Methods

alloc

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.

free

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.

isLowMemory

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.

Note: This method was deprecated in Gecko 2.0. If you need to monitor low memory conditions, you should watch for the Low memory notifications "memory-pressure" notifications instead.

boolean isLowMemory();
Parameters

None.

Return value

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

Note:  From Gecko 2.0 always returns false. See bug 592308.

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