nsIMemory

IID:59e7e77a-38e4-11d4-8cf5-0060b0fc14a3
Inherits From:nsISupports
Status:FROZEN

nsIMemory: interface to allocate and deallocate memory. Also provides for notifications in low-memory situations.

The frozen exported symbols NS_Alloc, NS_Realloc, and NS_Free provide a more efficient way to access XPCOM memory allocation. Using those symbols is preferred to using the methods on this interface.

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 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 implemented by the following components:


Methods

[noscript][notxpcom] voidPtr* alloc ( size_t size ) [noscript][notxpcom] void free ( voidPtr* ptr ) void heapMinimize ( PRBool immediate ) PRBool isLowMemory ( ) [noscript][notxpcom] voidPtr* realloc ( voidPtr* ptr , size_t newSize )

[notxpcom] voidPtr* alloc ( size_t size )

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.

Arguments:
size: - the size of the block to allocate

[notxpcom] void free ( voidPtr* ptr )

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

Arguments:
ptr: - the block of memory to free

void heapMinimize ( PRBool immediate )

Attempts to shrink the heap.

Arguments:
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.
Returns:
NS_ERROR_FAILURE if 'immediate' is set an the call was not on the application's main thread.

PRBool isLowMemory ( )

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


[notxpcom] voidPtr* realloc ( voidPtr* ptr , size_t newSize )

Reallocates a block of memory to a new size.

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.

Arguments:
ptr: - the block of memory to reallocate
newSize

References

This interface is passed as an argument to the following methods:

nsIPipe.init, nsIStorageStream.init

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
No comments available

Copyright © 1999 - 2005 XULPlanet.com