PageRenderTime 72ms CodeModel.GetById 50ms app.highlight 2ms RepoModel.GetById 18ms app.codeStats 0ms

/gecko_sdk/idl/nsIMemory.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 130 lines | 11 code | 8 blank | 111 comment | 0 complexity | fd2e0a5619635a40a59e4d37ae90c361 MD5 | raw file
  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is mozilla.org code.
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1998
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either of the GNU General Public License Version 2 or later (the "GPL"),
 26 * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38#include "nsISupports.idl"
 39
 40/**
 41 *
 42 * nsIMemory: interface to allocate and deallocate memory. Also provides
 43 * for notifications in low-memory situations.
 44 *
 45 * The frozen exported symbols NS_Alloc, NS_Realloc, and NS_Free
 46 * provide a more efficient way to access XPCOM memory allocation. Using
 47 * those symbols is preferred to using the methods on this interface.
 48 *
 49 * A client that wishes to be notified of low memory situations (for
 50 * example, because the client maintains a large memory cache that
 51 * could be released when memory is tight) should register with the
 52 * observer service (see nsIObserverService) using the topic 
 53 * "memory-pressure". There are three specific types of notications 
 54 * that can occur.  These types will be passed as the |aData| 
 55 * parameter of the of the "memory-pressure" notification: 
 56 * 
 57 * "low-memory"
 58 * This will be passed as the extra data when the pressure 
 59 * observer is being asked to flush for low-memory conditions.
 60 *
 61 * "heap-minimize"
 62 * This will be passed as the extra data when the pressure 
 63 * observer is being asked to flush because of a heap minimize 
 64 * call.
 65 *
 66 * "alloc-failure"
 67 * This will be passed as the extra data when the pressure 
 68 * observer has been asked to flush because a malloc() or 
 69 * realloc() has failed.
 70 *
 71 * @status FROZEN
 72 */
 73
 74[scriptable, uuid(59e7e77a-38e4-11d4-8cf5-0060b0fc14a3)]
 75interface nsIMemory : nsISupports
 76{
 77    /**
 78     * Allocates a block of memory of a particular size. If the memory 
 79     * cannot be allocated (because of an out-of-memory condition), null
 80     * is returned.
 81     *
 82     * @param size - the size of the block to allocate
 83     * @result the block of memory
 84     */
 85    [noscript, notxpcom] voidPtr alloc(in size_t size);
 86
 87    /**
 88     * Reallocates a block of memory to a new size.
 89     *
 90     * @param ptr - the block of memory to reallocate
 91     * @param size - the new size
 92     * @result the reallocated block of memory
 93     *
 94     * If ptr is null, this function behaves like malloc.
 95     * If s is the size of the block to which ptr points, the first
 96     * min(s, size) bytes of ptr's block are copied to the new block.
 97     * If the allocation succeeds, ptr is freed and a pointer to the 
 98     * new block returned.  If the allocation fails, ptr is not freed
 99     * and null is returned. The returned value may be the same as ptr.
100     */
101    [noscript, notxpcom] voidPtr realloc(in voidPtr ptr,
102                                         in size_t newSize);
103
104    /**
105     * Frees a block of memory. Null is a permissible value, in which case
106     * nothing happens. 
107     *
108     * @param ptr - the block of memory to free
109     */
110    [noscript, notxpcom] void free(in voidPtr ptr);
111
112    /**
113     * Attempts to shrink the heap.
114     * @param immediate - if true, heap minimization will occur
115     *   immediately if the call was made on the main thread. If
116     *   false, the flush will be scheduled to happen when the app is
117     *   idle.
118     * @return NS_ERROR_FAILURE if 'immediate' is set an the call
119     *   was not on the application's main thread.
120     */
121    void heapMinimize(in boolean immediate);
122
123    /**
124     * This predicate can be used to determine if we're in a low-memory
125     * situation (what constitutes low-memory is platform dependent). This
126     * can be used to trigger the memory pressure observers.
127     */
128    boolean isLowMemory();
129};
130