sharedMap.h

// Copyright 2009-2021 NTESS. Under the terms
// of Contract DE-NA0003525 with NTESS, the U.S.
// Government retains certain rights in this software.
//
// Copyright (c) 2009-2021, NTESS
// All rights reserved.
//
// This file is part of the SST software package. For license
// information, see the LICENSE file in the top level directory of the
// distribution.

#ifndef SST_CORE_CORE_SHARED_SHAREDMAP_H
#define SST_CORE_CORE_SHARED_SHAREDMAP_H

#include "sst/core/sst_types.h"
#include "sst/core/shared/sharedObject.h"

#include <map>

namespace SST {
namespace Shared {

/**
   SharedMap class.  The class is templated to allow for Map of any
   non-pointer type as value.  The type must be serializable.
 */
template <typename keyT, typename valT>
class SharedMap : public SharedObject {
    static_assert(!std::is_pointer<valT>::value, "Cannot use a pointer type as value with SharedMap");

    // Forward declaration.  Defined below
    class Data;

public:

    SharedMap() :
        SharedObject(), published(false), data(nullptr)
    {}

    ~SharedMap() {
        // data does not need to be deleted since the
        // SharedObjectManager owns the pointer
    }


    /**
       Initialize the SharedMap.

       @param obj_name Name of the object.  This name is how the
       object is uniquely identified across ranks.

       @param verify_mode Specifies how multiply written data should
       be verified.  Since the underlying map knows if the data has
       already been written, FE_VERIFY and INIT_VERIFY simply use this
       built-in mechanism to know when an item has previously been
       written.  When these modes are enabled, multiply written data
       must match what was written before.  When NO_VERIFY is passed,
       no verification will occur.  This is mostly useful when you can
       guarantee that multiple elements won't write the same value and
       you want to do in-place modifications as you initialize.
       VERIFY_UNINITIALIZED is a reserved value and should not be
       passed.

       @return returns the number of instances that have intialized
       themselve before this instance on this MPI rank.
     */
    int initialize(const std::string& obj_name, verify_type v_type = FE_VERIFY) {
        if ( data ) {
            Simulation::getSimulationOutput().fatal(
                CALL_INFO,1,"ERROR: called initialize() of SharedMap %s more than once\n",obj_name.c_str());
        }

        data = manager.getSharedObjectData<Data>(obj_name);
        int ret = incShareCount(data);
        data->setVerify(v_type);
        return ret;
    }

    /*** Typedefs and functions to mimic parts of the vector API ***/
    typedef typename std::map<keyT,valT>::const_iterator const_iterator;
    typedef typename std::map<keyT,valT>::const_reverse_iterator const_reverse_iterator;

    /**
       Get the size of the map.

       @return size of the map
     */
    inline size_t size() const { return data->getSize(); }

    /**
       Tests if the map is empty.

       @return true if map is empty, false otherwise
     */
    inline bool empty() const { return data->map.empty(); }


    /**
       Counts elements with a specific key.  Becuase this is not a
       multimap, it will either return 1 or 0.

       @return Count of elements with specified key
     */
    size_t count (const keyT& k) const {
        return data->map.count(k);
    }

    /**
       Searches the container for an element with a key equivalent to
       k and returns an iterator to it if found, otherwise it returns
       an iterator to SharedMap::end().

       @param key key to search for
     */
    const_iterator find (const keyT& key) const {
        return data->map.find(key);
    }

    /**
       Get const_iterator to beginning of underlying map
     */
    const_iterator begin() const {
        return data->map.cbegin();
    }

    /**
       Get const_iterator to end of underlying map
     */
    const_iterator end() const {
        return data->map.cend();
    }

    /**
       Get const_reverse_iterator to beginning of underlying map
     */
    const_reverse_iterator rbegin() const {
        return data->map.crbegin();
    }

    /**
       Get const_reverse_iterator to end of underlying map
     */
    const_reverse_iterator rend() const {
        return data->map.crend();
    }

    /**
       Returns an iterator pointing to the first element in the
       container whose key is not considered to go before k (i.e.,
       either it is equivalent or goes after).

       @param key key to compare to
     */
    inline const_iterator lower_bound(const keyT& key) const {
        return data->map.lower_bound(key);
    }

    /**
       Returns an iterator pointing to the first element in the
       container whose key is considered to go after k.

       @param key key to compare to
    */
    inline const_iterator upper_bound(const keyT& key) const {
        return data->map.lower_bound(key);
    }

    /**
       Indicate that the calling element has written all the data it
       plans to write.  Writing to the map through this instance
       after publish() is called will create an error.
     */
    void publish() {
        if ( published ) return;
        published = true;
        incPublishCount(data);
    }

    /**
       Check whether all instances of this SharedMap have called
       publish().  NOTE: Is is possible that this could return true
       one round, but false the next if a new instance of the
       SharedMap was initialized but not published after the last
       call.
     */
    bool isFullyPublished() {
        return data->isFullyPublished();
    }


    /**
       Write data to the map.  This function is thread-safe, as a
       mutex is used to ensure only one write at a time.

       @param key key of the write

       @param value value to be written
     */
    inline void write(const keyT& key, const valT& value) {
        if ( published ) {
            Simulation::getSimulationOutput().fatal(
                CALL_INFO,1,"ERROR: write to SharedMap %s after publish() was called\n",
                data->getName().c_str());
        }
        return data->write(key, value);
    }

    /**
       Read data from the map.  This returns a const reference, so is
       read only.  If the key is not in the map, an out_of_range
       exception will be thrown.

       NOTE: This function does not use a mutex, so it is possible to
       get invalid results if another thread is simulateously writing
       to the map.  However, after the init() phase of simulation is
       complete (in setup() and beyond), this is always a safe
       operation.  If reading during init() and you can't guarantee
       that all elements have already written all elements to the
       SharedMap, use mutex_read() to guarantee thread safety.

       @param key key to read

       @return const reference to data referenced by key

       @exception std::out_of_range key is not found in map
     */
    inline const valT& operator[](const keyT& key) const {
        return data->read(key);
    }

    /**
       Read data from the map.  This returns a const reference, so
       is read only.  This version of read is always thread safe (@see
       operator[]).  If the key is not in the map, an out_of_range
       exception will be thrown.

       @param key key to read

       @return const reference to data at index

       @exception std::out_of_range key is not found in map
    */
    inline const valT& mutex_read(const keyT& key) const {
        return data->mutex_read(key);
    }


private:
    bool published;
    Data* data;


    class Data : public SharedObjectData {

        // Forward declaration.  Defined below
        class ChangeSet;

    public:

        std::map<keyT,valT> map;
        ChangeSet* change_set;
        verify_type verify;

        Data(const std::string& name) :
            SharedObjectData(name),
            change_set(nullptr),
            verify(VERIFY_UNINITIALIZED)
        {
            if ( Simulation::getSimulation()->getNumRanks().rank > 1 ) {
                change_set = new ChangeSet(name);
            }
        }

        ~Data() {
            delete change_set;
        }

        void setVerify(verify_type v_type) {
            if ( v_type != verify && verify != VERIFY_UNINITIALIZED ) {
                Simulation::getSimulationOutput().fatal(
                    CALL_INFO,1,"ERROR: Two different verify_types specified for SharedMap %s\n",name.c_str());
            }
            verify = v_type;
            if ( change_set ) change_set->setVerify(v_type);
        }

        size_t getSize() const {
            return map.size();
        }

        void update_write(const keyT& key, const valT& value) {
            // Don't need to mutex because this is only ever called
            // from one thread at a time, with barrier before and
            // after, or from write(), which does mutex.
            auto success = map.insert(std::make_pair(key,value));
            if ( !success.second ) {
                // Wrote to a key that already existed
                if ( verify != NO_VERIFY && value != success.first->second ) {
                    Simulation::getSimulationOutput().fatal(
                        CALL_INFO, 1, "ERROR: wrote two different values to same key in SharedMap %s\n",name.c_str());
                }
            }
        }

        void write(const keyT& key, const valT& value) {
            std::lock_guard<std::mutex> lock(mtx);
            check_lock_for_write("SharedMap");
            update_write(key,value);
            if ( change_set ) change_set->addChange(key,value);
        }

        // Inline the read since it may be called often during run().
        // This read is not protected from data races in the case
        // where the map may be simulataeously written by another
        // thread.  If there is a danger of simultaneous access
        // during init, use the mutex_read function until after the
        // init phase.
        inline const valT& read(const keyT& key) {
            return map.at(key);
        }

        // Mutexed read for use if you are resizing the array as you go
        inline const valT& mutex_read(const keyT& key) {
            std::lock_guard<std::mutex> lock(mtx);
            auto ret = map.at(key);
            return ret;
        }

        // Functions inherited from SharedObjectData
        virtual SharedObjectChangeSet* getChangeSet() override {
            return change_set;
        }
        virtual void resetChangeSet() override {
            change_set->clear();
        }

    private:
        class ChangeSet : public SharedObjectChangeSet {

            std::map<keyT,valT> changes;
            verify_type verify;

            void serialize_order(SST::Core::Serialization::serializer& ser) override {
                SharedObjectChangeSet::serialize_order(ser);
                ser & changes;
                ser & verify;
            }

            ImplementSerializable(SST::Shared::SharedMap<keyT,valT>::Data::ChangeSet);

        public:
            // For serialization
            ChangeSet() :
                SharedObjectChangeSet(),
                verify(VERIFY_UNINITIALIZED)
                {}
            ChangeSet(const std::string& name) :
                SharedObjectChangeSet(name),
                verify(VERIFY_UNINITIALIZED)
                {}

            void addChange(const keyT& key, const valT& value) {
                changes[key] = value;
            }

            void setVerify(verify_type v_type) {
                verify = v_type;
            }

            void applyChanges(SharedObjectDataManager* manager) override {
                auto data = manager->getSharedObjectData<Data>(getName());
                data->setVerify(verify);
                for ( auto x : changes ) {
                    data->update_write(x.first, x.second);
                }
            }

            void clear() override {
                changes.clear();
            }
        };
    };



};

} // namespace Shared
} // namespace SST

#endif