.. _almemory: ALMemory ======== .. toctree:: :hidden: :maxdepth: 1 almemory-api almemory-tuto Overview | :ref:`API ` | :ref:`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-micro-event: 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 :cpp:func:`ALMemoryProxy::getEventHistory`. Furthermore Module can autostart when someone subscribe to an Event. This feature is accessible using :cpp:func:`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 :cpp:func:`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 [] 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 :cpp:func:`ALMemoryProxy::getDataPtr` and :cpp:func:`ALMemoryProxy::getData`. * :cpp:func:`ALMemoryProxy::getDataPtr` provides fast pointer access. **Warning**: it's not thread safe nor atomic. * :cpp:func:`ALMemoryProxy::getData` provides thread safe access. It can be used either when your module is local or remote. To store values in the memory, use :cpp:func:`ALMemoryProxy::insertData`. To subscribe to events, use the following functions: * :cpp:func:`ALMemoryProxy::subscribeToMicroEvent` subscribe to an event. * :cpp:func:`ALMemoryProxy::subscribeToEvent` subscribe to a microevent. Look at the following example for details: :ref:`cpp-tutos-create-events` To generate events, use the following functions: * :cpp:func:`ALMemoryProxy::raiseMicroEvent`: inserts a value and notifies subscribers. * :cpp:func:`ALMemoryProxy::raiseEvent`: inserts a value, notifies subscribers, stores value history and timestamp (internal). * :cpp:func:`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.