sharedRegion.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_SHAREDREGION_H
#define SST_CORE_CORE_SHAREDREGION_H

#include "sst/core/warnmacros.h"
#include "sst/core/sst_types.h"

#include <string>
#include <vector>

#if !SST_BUILDING_CORE
#warning "SharedRegion and its accompanying classes have been deprecated and will be removed in SST 12. Please use the new SharedObject classes found in sst/core/shared."
#endif

namespace SST {

class SharedRegion;
class ChangeSet;

/**
 * Utility class to define how to merge multiple pieces of shared memory regions
 * Useful in the multi-MPI-rank, "Global Shared" model
 */
class SharedRegionMerger {
public:

    virtual ~SharedRegionMerger() { }

    /**
     * Merge the data from 'newData' into 'target'
     * @return True on success, False on failure
     */
    virtual bool merge(uint8_t *target, const uint8_t *newData, size_t size);
    virtual bool merge(uint8_t *target, size_t size, const std::vector<ChangeSet> &changeSets);
};


class SharedRegionInitializedMerger : public SharedRegionMerger {
    uint8_t defVal;
public:
    SharedRegionInitializedMerger(uint8_t defaultValue) {
        defVal = defaultValue;
    }

    bool merge(uint8_t *target, const uint8_t *newData, size_t size) override;

    bool merge(uint8_t *target, size_t size, const std::vector<ChangeSet> &changeSets) override {
        return SharedRegionMerger::merge(target,size,changeSets);
    }

};


class SharedRegionManager {
protected:
    friend class SharedRegion;

    virtual void modifyRegion(SharedRegion *sr, size_t offset, size_t length, const void *data) = 0;
    virtual void* getMemory(SharedRegion* sr) = 0;
    virtual const void* getConstPtr(const SharedRegion* sr) const = 0;
    virtual size_t getSize(const SharedRegion* sr) const = 0;

public:

    /**
       Create a SharedRegion that will only be shared with elements on
       the current rank.  This type of SharedRegion is intended to
       have at least one element on each rank initialize the region.

       @param key Name of the SharedRegion.  All elements om the rank
       using this name will get the same underlying data.

       @param size Size of the SharedRegion.  Elements can specify 0
       size if they don't know the size of the region.  At least one
       element will need to specify the size and all elements that
       specify a size must pass in the same size.  There are many
       calls in SharedRegion that can't be called until the size is
       known.

       @param initByte Value to initialize all bytes in the region to

       @return SharedRegion object to be used by the calling element
       to access the shared region.
     */
    virtual SharedRegion* getLocalSharedRegion(const std::string& key, size_t size, uint8_t initByte = 0) = 0;

    /**
       Create a SharedRegion that will be shared with elements on the
       all ranks.  The SharedRegion data will be merged across ranks
       before each round of calls to init().

       @param key Name of the SharedRegion.  All elements using this
       name will get the same underlying data.

       @param size Size of the SharedRegion.  Elements can specify 0
       size if they don't know the size of the region.  At least one
       element will need to specify the size and all elements that
       specify a size must pass in the same size.  There are many
       calls in SharedRegion that can't be called until the size is
       known.

       @param merger Merger to use when combining data across ranks

       @param initByte Value to initialize all bytes in the region to

       @return SharedRegion object to be used by the calling element
       to access the shared region.
    */
    virtual SharedRegion* getGlobalSharedRegion(const std::string& key, size_t size, SharedRegionMerger *merger = nullptr, uint8_t initByte = 0) = 0;


    // The following functions will become protected in SST 12.  Need
    // to look for instances of these used in the core, they will be
    // bracketed with DISABLE_WARN_DEPRECATED_DECLARATION.
    virtual void publishRegion(SharedRegion*) = 0;

    virtual bool isRegionReady(const SharedRegion*) = 0;

    virtual void shutdownSharedRegion(SharedRegion*) = 0;

    virtual void updateState(bool finalize) = 0;

};

class SharedRegion {
private:
    SharedRegionManager *manager;
    size_t id;



protected:

    class DeferredPointerBase {
    public:
        virtual ~DeferredPointerBase() {}
        virtual void setPointer(const void *p) = 0;
    };

    template <typename T>
    class DeferredPointer : public DeferredPointerBase {
        T& ptr;

    public:
        DeferredPointer(T& ptr) : DeferredPointerBase(), ptr(ptr) {}

        void setPointer(const void *p) {
            ptr = static_cast<const T>(p);
        }
    };

    DeferredPointerBase* deferred_pointer;

    SharedRegion(SharedRegionManager *manager, size_t id) :
        manager(manager),
        id(id),
        deferred_pointer(nullptr)
    { }

public:

    virtual ~SharedRegion()
    { }

    void shutdown() {
        DISABLE_WARN_DEPRECATED_DECLARATION ;
        manager->shutdownSharedRegion(this);
        REENABLE_WARNING;
    }

    /**
     * @return The ID of this instance. (Number in range 0->N)
     */
    size_t getLocalShareID() const { return id; }

    /**
     * @return The size of the shared memory region, may return 0 if
     * this copy of the region doesn't know the final size yet.
     */
    size_t getSize() const { return manager->getSize(this); }

    /**
     * Call to denote that you are done making any changes to this region
     */
    void publish() {
        DISABLE_WARN_DEPRECATED_DECLARATION;
        manager->publishRegion(this);
        REENABLE_WARNING;
    }


    /**
     * Check to see if the region is ready (all elements requesting
     * the region have called publish()).
     *
     * @return True if the region is ready to use (all sharers have
     * called publish()).
     */
    bool isReady() const {
        DISABLE_WARN_DEPRECATED_DECLARATION;
        return manager->isRegionReady(this);
        REENABLE_WARNING;
    }


    /**
     * Before the region has published, apply a modification. (Copy
     * this data in).  This function cannot be called if the size is
     * still set to 0.
     */
    void modifyRegion(size_t offset, size_t length, const void *data)
    { manager->modifyRegion(this, offset, length, data); }

    /**
     * Before the region has published, apply a modification. (Copy
     * this data in).  This function cannot be called if the size is
     * still set to 0.
     */
    template<typename T>
    void modifyArray(size_t offset, const T &data)
    { manager->modifyRegion(this, offset*sizeof(T), sizeof(T), &data); }

    /**
     * @return a void* pointer to the shared memory region This
     * pointer is only valid to write to before a call to publish().
     * This function cannot be called if the size is still set to
     * 0, as there is no backing memory yet.
     */
    void* getRawPtr() { return manager->getMemory(this); }

    /**
     * Get a pointer to the const shared data
     *
     * @return a const pointer to the shared memory region.  This
     * function cannot be called if the size is still set to
     * 0, as there is no backing memory yet.
     */
    template<typename T>
    T getPtr() const {
        return static_cast<T>(manager->getConstPtr(this));
    }


    /**
     * Used to get a pointer to the const shared data when the element
     * doesn't yet know the size.  This will defer setting the pointer
     * until the size of the region is known (and therefor the memory
     * has been allocated).  This allows an element to initialize the
     * region and get the pointer without having to make the call to
     * getPtr() later.  This is particularly helpful if the
     * SharedRegion is created in an object that doesn't get called
     * during init() or setup().
     *
     * @ptr Pointer that should be set once the size is known.  User
     * can tell pointer is valid when getSize() returns a value != 0.
     */
    template<typename T>
    void getPtrDeferred(T& ptr) {
        if ( getSize() != 0 ) {
            // Size is already set, just set the pointer
            ptr = getPtr<T>();
            return;
        }
        if ( deferred_pointer != nullptr ) return;
        deferred_pointer = new DeferredPointer<T>(ptr);
    }


};



}


#endif