MemoryInfo

Since: BlackBerry 10.0.0

#include <bb/MemoryInfo>

To link against this class, add the following line to your .pro file: LIBS += -lbb

The MemoryInfo class provides notifications about low device memory.

Instances of this class provide a signal informing the application that device memory is running low. Applications can listen for this signal to free memory to avoid potential performance degradations and application crashes.

Note that, once created, instances of this class cannot have their thread affinity changed, either explicitly via QObject::moveToThread() or implicitly by changing the thread affinity of the parent of the object. Doing so results in undefined behavior.


Overview

Public Functions Index

MemoryInfo (QObject *parent=0)
virtual ~MemoryInfo ()
Q_INVOKABLE qint64availableDeviceMemory () const
Q_INVOKABLE qint64memoryUsedByCurrentProcess () const
Q_INVOKABLE qint64totalDeviceMemory () const

Signals Index

voidlowMemory (bb::LowMemoryWarningLevel::Type level)

Public Functions

MemoryInfo (

Creates a new MemoryInfo object.

Example usage in C++

#include <bb/MemoryInfo>

int main(int argc, char **argv)
{
    bb::MemoryInfo memoryInfo;
}
Example usage in QML
// QML Plugin for libbb
import bb 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // MemoryInfo isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            MemoryInfo {
                id: memoryInfo
            }
        ]
        
        // Additional QML, which can use memoryInfo
    }
}
Parameters
parent

If not 0, the supplied parent will be responsible for deleting this instance.

Since:

BlackBerry 10.0.0

virtual~MemoryInfo ()

Destructor.

Since:

BlackBerry 10.0.0

Q_INVOKABLE qint64 availableDeviceMemory ()

Returns the current amount of free memory on the device in bytes.

Example usage in C++
#include <bb/MemoryInfo>

void initializeCache()
{
    bb::MemoryInfo memoryInfo;
    qint64 availableMemory = memoryInfo.availableDeviceMemory();
    if (availableMemory >= CACHE_THRESHOLD) {
        // Only create cache if device has enough available memory for one.
        createAndPopulateCache(availableMemory);
    }
}
Example usage in QML
// QML Plugin for libbb
import bb 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // MemoryInfo isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            MemoryInfo {
                id: memoryInfo
            }
        ]
        
        Button {
            text: "Initialize Cache"
            onClicked: {
                var availableMemory = memoryInfo.availableDeviceMemory();
                if (availableMemory >= CACHE_THRESHOLD) {
                    // Only create cache if device has enough available memory for one.
                    createAndPopulateCache(availableMemory);
                }
            }
        }
        // Additional QML
    }
}
Return:

The current amount of free memory on the device in bytes, or -1 in the event of an error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE qint64 memoryUsedByCurrentProcess ()

Returns the amount of memory allocated for this process in bytes.

This is the amount of memory that the OS has allocated to the process. Due to the structure of C/C++ memory managers (memory is obtained from the OS in chunks and cached by the memory manager), a call to new, delete, malloc, or free, will not necessarily change the value returned by this function.

Example usage in C++
#include <bb/MemoryInfo>

void reduceCacheSize()
{
    bb::MemoryInfo memoryInfo;
    qint64 currentMemoryUsage = memoryInfo.memoryUsedByCurrentProcess();
    if (currentMemoryUsage > THRESHOLD) {
        // Too big - reduce the size
        reduceCache(currentMemoryUsage);
    }
}
Example usage in QML
// QML Plugin for libbb
import bb 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // MemoryInfo isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            MemoryInfo {
                id: memoryInfo
            }
        ]
        
        Button {
            text: "Reduce Cache Size"
            onClicked: {
                var currentMemoryUsage = memoryInfo.memoryUsedByCurrentProcess();
                if (currentMemoryUsage > THRESHOLD) {
                    // Too big - reduce the size
                    reduceCache(currentMemoryUsage);
                }
            }
        }
        // Additional QML
    }
}
Return:

The amount of memory allocated for this process in bytes, or -1 in the event of an error.

Since:

BlackBerry 10.0.0

Q_INVOKABLE qint64 totalDeviceMemory ()

Returns the total amount of memory on the device in bytes.

Example usage in C++
#include <bb/MemoryInfo>

void initializeCache()
{
    bb::MemoryInfo memoryInfo;
    qint64 totalMemory = memoryInfo.totalDeviceMemory();
    if (totalMemory >= CACHE_THRESHOLD) {
        // Only create cache if device has enough memory for one.
        createAndPopulateCache(totalMemory);
    }
}
Example usage in QML
// QML Plugin for libbb
import bb 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // MemoryInfo isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            MemoryInfo {
                id: memoryInfo
            }
        ]
        
        Button {
            text: "Initialize Cache"
            onClicked: {
                var totalMemory = memoryInfo.totalDeviceMemory();
                if (totalMemory >= CACHE_THRESHOLD) {
                    // Only create cache if device has enough memory for one.
                    createAndPopulateCache(totalMemory);
                }
            }
        }
        // Additional QML
    }
}
Return:

The total amount of memory on the device in bytes.

Since:

BlackBerry 10.0.0

Signals

void lowMemory (

Emitted when the device detects that it is running low on memory.

Any slot attached to this signal is notified when the device detects that memory is running low. A device in this state may experience degraded performance and possibly application crashes if the situation is not rectified.

To avoid these problems, when this signal is received the application should release as much memory as possible. For example, the application could free cached items that can be re-obtained later, or release memory for images that can be re-read from the file system.

The parameter level provides an indication of the severity of the memory situation on the device. Values for this parameter are:

If memory continues to run low after a high priority warning, applications may be asked to exit. This exit process is identical to the application being shut down by the user, including the opportunity to clean up and save application state.

Note that the device may skip some of these indications and steps depending on whether the memory situation improves or worsens over time.

If memory continues to run low after applications are asked to exit, then applications may be terminated without warning and without any chance to perform any cleanup or save any state.

Example usage in C++
void TestObject::onLowMemory(bb::LowMemoryWarningLevel level) {
    if (level == bb::LowMemoryWarningLevel::LowPriority) {
        releaseLowPriorityMemory();
    } else if (level == bb::LowMemoryWarningLevel::HighPriority) {
        releaseHighPriorityMemory();
    }
}

int main(int argc, char **argv) {
    bb::Application app(argc, argv);
    bb::MemoryInfo memoryInfo;
    TestObject testObject;

    QObject::connect(&memoryInfo, SIGNAL( lowMemory(bb::LowMemoryWarningLevel::Type) ),
                     &testObject, SLOT( onLowMemory(bb::LowMemoryWarningLevel::Type) ));
See full example
Example use in QML
// QML Plugin for libbb
import bb 1.0

import bb.cascades 1.0

Page {
    Container {
    
        // MemoryInfo isn't a visible object so it must be wrapped as an
        // attached object.
        attachedObjects: [
            MemoryInfo {
                id: memoryInfo
                
                onLowMemory: {
                    if (level == LowMemoryWarningLevel.LowPriority) {
                        releaseLowPriorityMemory();
                    } else if (level == bb::LowMemoryWarningLevel::HighPriority) {
                        releaseHighPriorityMemory();
                    }
                }
            }
        ]
        
        // Additional QML, which can use memoryInfo
    }
}
Parameters
level

The level of the low memory warning, indicating the importance and priority of the warning.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus