1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/xpcom/base/nsIMemory.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,115 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +/**
1.12 + *
1.13 + * nsIMemory: interface to allocate and deallocate memory. Also provides
1.14 + * for notifications in low-memory situations.
1.15 + *
1.16 + * The frozen exported symbols NS_Alloc, NS_Realloc, and NS_Free
1.17 + * provide a more efficient way to access XPCOM memory allocation. Using
1.18 + * those symbols is preferred to using the methods on this interface.
1.19 + *
1.20 + * A client that wishes to be notified of low memory situations (for
1.21 + * example, because the client maintains a large memory cache that
1.22 + * could be released when memory is tight) should register with the
1.23 + * observer service (see nsIObserverService) using the topic
1.24 + * "memory-pressure". There are three specific types of notications
1.25 + * that can occur. These types will be passed as the |aData|
1.26 + * parameter of the of the "memory-pressure" notification:
1.27 + *
1.28 + * "low-memory"
1.29 + * This will be passed as the extra data when the pressure
1.30 + * observer is being asked to flush for low-memory conditions.
1.31 + *
1.32 + * "low-memory-ongoing"
1.33 + * This will be passed when we continue to be in a low-memory
1.34 + * condition and we want to flush caches and do other cheap
1.35 + * forms of memory minimization, but heavy handed approaches like
1.36 + * a GC are unlikely to succeed.
1.37 + *
1.38 + * "-no-forward"
1.39 + * This is appended to the above two parameters when the resulting
1.40 + * notification should not be forwarded to the child processes.
1.41 + *
1.42 + * "heap-minimize"
1.43 + * This will be passed as the extra data when the pressure
1.44 + * observer is being asked to flush because of a heap minimize
1.45 + * call.
1.46 + *
1.47 + * "alloc-failure"
1.48 + * This will be passed as the extra data when the pressure
1.49 + * observer has been asked to flush because a malloc() or
1.50 + * realloc() has failed.
1.51 + */
1.52 +
1.53 +[scriptable, uuid(6aef11c4-8615-44a6-9711-98f43805693d)]
1.54 +interface nsIMemory : nsISupports
1.55 +{
1.56 + /**
1.57 + * Allocates a block of memory of a particular size. If the memory
1.58 + * cannot be allocated (because of an out-of-memory condition), the
1.59 + * process aborts.
1.60 + *
1.61 + * @param size - the size of the block to allocate
1.62 + * @result the block of memory
1.63 + */
1.64 + [noscript, notxpcom] voidPtr alloc(in size_t size);
1.65 +
1.66 + /**
1.67 + * Reallocates a block of memory to a new size.
1.68 + *
1.69 + * @param ptr - the block of memory to reallocate
1.70 + * @param size - the new size
1.71 + * @result the reallocated block of memory
1.72 + *
1.73 + * If ptr is null, this function behaves like malloc.
1.74 + * If s is the size of the block to which ptr points, the first
1.75 + * min(s, size) bytes of ptr's block are copied to the new block.
1.76 + * If the allocation succeeds, ptr is freed and a pointer to the
1.77 + * new block returned. If the allocation fails, the process aborts.
1.78 + */
1.79 + [noscript, notxpcom] voidPtr realloc(in voidPtr ptr,
1.80 + in size_t newSize);
1.81 +
1.82 + /**
1.83 + * Frees a block of memory. Null is a permissible value, in which case
1.84 + * nothing happens.
1.85 + *
1.86 + * @param ptr - the block of memory to free
1.87 + */
1.88 + [noscript, notxpcom] void free(in voidPtr ptr);
1.89 +
1.90 + /**
1.91 + * Attempts to shrink the heap.
1.92 + * @param immediate - if true, heap minimization will occur
1.93 + * immediately if the call was made on the main thread. If
1.94 + * false, the flush will be scheduled to happen when the app is
1.95 + * idle.
1.96 + * @throws NS_ERROR_FAILURE if 'immediate' is set an the call
1.97 + * was not on the application's main thread.
1.98 + */
1.99 + void heapMinimize(in boolean immediate);
1.100 +
1.101 + /**
1.102 + * This predicate can be used to determine if we're in a low-memory
1.103 + * situation (what constitutes low-memory is platform dependent). This
1.104 + * can be used to trigger the memory pressure observers.
1.105 + *
1.106 + * DEPRECATED - Always returns false. See bug 592308.
1.107 + */
1.108 + boolean isLowMemory();
1.109 +
1.110 + /**
1.111 + * This predicate can be used to determine if the platform is a "low-memory"
1.112 + * platform. Callers may use this to dynamically tune their behaviour
1.113 + * to favour reduced memory usage at the expense of performance. The value
1.114 + * returned by this function will not change over the lifetime of the process.
1.115 + */
1.116 + boolean isLowMemoryPlatform();
1.117 +};
1.118 +
