The Tor Browser / file comparison
comparison: xpcom/base/nsIMemory.idl
xpcom/base/nsIMemory.idl
- branch
- TOR_BUG_3246
- changeset 7
- 129ffea94266
equal
deleted
inserted
replaced
| -1:000000000000 | 0:7d3fdfd85b01 |
|---|---|
| 1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ | |
| 2 /* This Source Code Form is subject to the terms of the Mozilla Public | |
| 3 * License, v. 2.0. If a copy of the MPL was not distributed with this | |
| 4 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ | |
| 5 | |
| 6 #include "nsISupports.idl" | |
| 7 | |
| 8 /** | |
| 9 * | |
| 10 * nsIMemory: interface to allocate and deallocate memory. Also provides | |
| 11 * for notifications in low-memory situations. | |
| 12 * | |
| 13 * The frozen exported symbols NS_Alloc, NS_Realloc, and NS_Free | |
| 14 * provide a more efficient way to access XPCOM memory allocation. Using | |
| 15 * those symbols is preferred to using the methods on this interface. | |
| 16 * | |
| 17 * A client that wishes to be notified of low memory situations (for | |
| 18 * example, because the client maintains a large memory cache that | |
| 19 * could be released when memory is tight) should register with the | |
| 20 * observer service (see nsIObserverService) using the topic | |
| 21 * "memory-pressure". There are three specific types of notications | |
| 22 * that can occur. These types will be passed as the |aData| | |
| 23 * parameter of the of the "memory-pressure" notification: | |
| 24 * | |
| 25 * "low-memory" | |
| 26 * This will be passed as the extra data when the pressure | |
| 27 * observer is being asked to flush for low-memory conditions. | |
| 28 * | |
| 29 * "low-memory-ongoing" | |
| 30 * This will be passed when we continue to be in a low-memory | |
| 31 * condition and we want to flush caches and do other cheap | |
| 32 * forms of memory minimization, but heavy handed approaches like | |
| 33 * a GC are unlikely to succeed. | |
| 34 * | |
| 35 * "-no-forward" | |
| 36 * This is appended to the above two parameters when the resulting | |
| 37 * notification should not be forwarded to the child processes. | |
| 38 * | |
| 39 * "heap-minimize" | |
| 40 * This will be passed as the extra data when the pressure | |
| 41 * observer is being asked to flush because of a heap minimize | |
| 42 * call. | |
| 43 * | |
| 44 * "alloc-failure" | |
| 45 * This will be passed as the extra data when the pressure | |
| 46 * observer has been asked to flush because a malloc() or | |
| 47 * realloc() has failed. | |
| 48 */ | |
| 49 | |
| 50 [scriptable, uuid(6aef11c4-8615-44a6-9711-98f43805693d)] | |
| 51 interface nsIMemory : nsISupports | |
| 52 { | |
| 53 /** | |
| 54 * Allocates a block of memory of a particular size. If the memory | |
| 55 * cannot be allocated (because of an out-of-memory condition), the | |
| 56 * process aborts. | |
| 57 * | |
| 58 * @param size - the size of the block to allocate | |
| 59 * @result the block of memory | |
| 60 */ | |
| 61 [noscript, notxpcom] voidPtr alloc(in size_t size); | |
| 62 | |
| 63 /** | |
| 64 * Reallocates a block of memory to a new size. | |
| 65 * | |
| 66 * @param ptr - the block of memory to reallocate | |
| 67 * @param size - the new size | |
| 68 * @result the reallocated block of memory | |
| 69 * | |
| 70 * If ptr is null, this function behaves like malloc. | |
| 71 * If s is the size of the block to which ptr points, the first | |
| 72 * min(s, size) bytes of ptr's block are copied to the new block. | |
| 73 * If the allocation succeeds, ptr is freed and a pointer to the | |
| 74 * new block returned. If the allocation fails, the process aborts. | |
| 75 */ | |
| 76 [noscript, notxpcom] voidPtr realloc(in voidPtr ptr, | |
| 77 in size_t newSize); | |
| 78 | |
| 79 /** | |
| 80 * Frees a block of memory. Null is a permissible value, in which case | |
| 81 * nothing happens. | |
| 82 * | |
| 83 * @param ptr - the block of memory to free | |
| 84 */ | |
| 85 [noscript, notxpcom] void free(in voidPtr ptr); | |
| 86 | |
| 87 /** | |
| 88 * Attempts to shrink the heap. | |
| 89 * @param immediate - if true, heap minimization will occur | |
| 90 * immediately if the call was made on the main thread. If | |
| 91 * false, the flush will be scheduled to happen when the app is | |
| 92 * idle. | |
| 93 * @throws NS_ERROR_FAILURE if 'immediate' is set an the call | |
| 94 * was not on the application's main thread. | |
| 95 */ | |
| 96 void heapMinimize(in boolean immediate); | |
| 97 | |
| 98 /** | |
| 99 * This predicate can be used to determine if we're in a low-memory | |
| 100 * situation (what constitutes low-memory is platform dependent). This | |
| 101 * can be used to trigger the memory pressure observers. | |
| 102 * | |
| 103 * DEPRECATED - Always returns false. See bug 592308. | |
| 104 */ | |
| 105 boolean isLowMemory(); | |
| 106 | |
| 107 /** | |
| 108 * This predicate can be used to determine if the platform is a "low-memory" | |
| 109 * platform. Callers may use this to dynamically tune their behaviour | |
| 110 * to favour reduced memory usage at the expense of performance. The value | |
| 111 * returned by this function will not change over the lifetime of the process. | |
| 112 */ | |
| 113 boolean isLowMemoryPlatform(); | |
| 114 }; | |
| 115 |
