ALMemory

Overview | API | Tutorial

What it does

ALMemory provides a centralized memory that can be used to store and retrieve named values. It also acts as a hub for the distribution of event notifications.

How it works

ALMemory is a mutexed and unordered boost map. The map contains variant (ALValue).

Mutex are read/write mutex and for performance, can protect:

  • The map
  • A value
  • The value history (only for events)

For example:

  • Remove a data blocks all readers/writers.
  • Insert an existing data only blocks the modified data.
  • Read data blocks only writers of read data.

The notifications are managed by a threadpool (in local) or by a unique notification thread (in remote).

Event and MicroEvent

Event is a MicroEvent which store his history into ALMemory. They are basically the same, but MicroEvent is faster.

You can access to event history using ALMemoryProxy::getEventHistory.

Furthermore Module can autostart when someone subscribe to an Event. This feature is accessible using ALMemoryProxy::declareEvent with two parameters.

Performances and Limitations

ALMemory is thread safe for normal operations. Reader and writer can access variable at the same moment except when you use ALMemoryProxy::getDataPtr.

AMD Geode performance:

Method Performance
10 insertData 0.01 ms
10 raiseMicroEvent 0.015ms
10 raiseEvent 0.02 ms
10 python insertData 1.0 ms

ALMemory can store and retreive variant (ALValue):

type C++ Python Java
integer int Python integer int
boolean bool Python boolean Boolean
float float Python float Float
List vector<ALValue> [] Java array []
String std::string Python string String
Binary ALValue String byte[]
Variant ALValue Use python type jnaoqi Variant

Getting started

To access to a value stored in ALMemory, use ALMemoryProxy::getDataPtr and ALMemoryProxy::getData.

To store values in the memory, use ALMemoryProxy::insertData.

To subscribe to events, use the following functions:

Look at the following example for details: Creating events

To generate events, use the following functions:

  • ALMemoryProxy::raiseMicroEvent: inserts a value and notifies subscribers.
  • ALMemoryProxy::raiseEvent: inserts a value, notifies subscribers, stores value history and timestamp (internal).
  • ALMemoryProxy::declareEvent: links a module to a variable. If a module subscribes to variable, the module starts his process once. For example, subscribe to FaceDetected automatically starts the module ALFaceDetection. If all subscribers unsubscribe, the module stops.
« ALModule API | NAOqi Core | ALMemory API »
« previous | up | next »