ALMemory

NAOqi Core - Overview | API

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 retrieve 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:

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.

Examples

Look at the following examples for details:

« NetworkInfo-IPInfo | NAOqi Core | ALMemory API »
« previous | up | next »