serialize_array.h

// Copyright 2009-2026 NTESS. Under the terms
// of Contract DE-NA0003525 with NTESS, the U.S.
// Government retains certain rights in this software.
//
// Copyright (c) 2009-2026, 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_SERIALIZATION_IMPL_SERIALIZE_ARRAY_H
#define SST_CORE_SERIALIZATION_IMPL_SERIALIZE_ARRAY_H
 
#ifndef SST_INCLUDING_SERIALIZE_H
#warning \
    "The header file sst/core/serialization/impl/serialize_array.h should not be directly included as it is not part of the stable public API.  The file is included in sst/core/serialization/serialize.h"
#endif
 
#include "sst/core/serialization/serializer.h"
 
#include <array>
#include <cstddef>
#include <type_traits>
 
namespace SST::Core::Serialization {
 
// Serialize arrays
 
namespace pvt {
 
// Wrapper classes. They have no declared constructors so that they can be aggregate-initialized.
template <typename ELEM_T, typename SIZE_T>
struct array_wrapper
{
    ELEM_T*& ptr;
    SIZE_T&  size;
};
 
template <typename ELEM_T>
struct raw_ptr_wrapper
{
    ELEM_T*& ptr;
};
 
} // namespace pvt
 
// Wrapper functions
 
template <typename ELEM_T, typename SIZE_T>
pvt::array_wrapper<ELEM_T, SIZE_T>
array(ELEM_T*& ptr, SIZE_T& size)
{
    return { ptr, size };
}
 
template <typename SIZE_T>
pvt::array_wrapper<void, SIZE_T>
buffer(void*& ptr, SIZE_T& size)
{
    return { ptr, size };
}
 
template <typename ELEM_T>
pvt::raw_ptr_wrapper<ELEM_T>
raw_ptr(ELEM_T*& ptr)
{
    return { ptr };
}
 
/**
   Class used to map unbounded arrays with runtime size
 */
template <class ELEM_T, class SIZE_T>
class ObjectMapArray : public ObjectMapContainer<ELEM_T>
{
protected:
    SIZE_T& size_;
 
public:
    virtual size_t getSize() const { return size_; }
    ObjectMapArray(ELEM_T* addr, SIZE_T& size) :
        ObjectMapContainer<ELEM_T>(addr),
        size_(size)
    {}
    void refresh() override
    {
        // Decrement the reference count of all children, which will be replaced
        for ( const auto& [name, child] : this->variables_ )
            if ( child != nullptr ) child->decRefCount();
 
        // Replace the children with new children by re-serializing the array
        // ObjectMapSerialization(array(this->addr_, size_)) returns an ObjectMap* to a new serialization of the array
        // dynamic_cast<ObjectMapArray&> downcasts the returned ObjectMap to this ObjectMapArray
        // std::move improves performance, by shallow-moving the new variables_ into this class's variables_
        this->variables_ =
            std::move(dynamic_cast<ObjectMapArray&>(*ObjectMapSerialization(array(this->addr_, size_))).variables_);
    }
    ~ObjectMapArray() override = default;
};
 
namespace pvt {
 
// Functions for serializing arrays element by element
void serialize_array(serializer& ser, void* data, ser_opt_t opt, size_t size,
    void serialize_array_element(serializer& ser, void* data, ser_opt_t opt, size_t index));
 
void serialize_array_map(serializer& ser, void* data, ser_opt_t opt, size_t size, ObjectMap* map,
    void serialize_array_map_element(serializer& ser, void* data, ser_opt_t opt, size_t index, const char* name));
 
// Serialize an array element
// Separated out to reduce code size
template <typename ELEM_T>
void
serialize_array_element(serializer& ser, void* data, ser_opt_t opt, size_t index)
{
    SST_SER(static_cast<ELEM_T*>(data)[index], opt);
}
 
// Serialize an array map element
// Separated out to reduce code size
template <typename ELEM_T>
void
serialize_array_map_element(serializer& ser, void* data, ser_opt_t opt, size_t index, const char* name)
{
    SST_SER_NAME(static_cast<ELEM_T*>(data)[index], name, opt);
}
 
// Serialize fixed arrays
// ELEM_T:   Array element type
// SIZE:     Fixed array size
// OBJ_TYPE: Complete type of object being serialized
template <typename OBJ_TYPE, typename ELEM_T, size_t SIZE>
struct serialize_impl_fixed_array
{
    void operator()(OBJ_TYPE& ary, serializer& ser, ser_opt_t opt)
    {
        using T              = std::remove_pointer_t<OBJ_TYPE>;
        ser_opt_t   elem_opt = SerOption::is_set(opt, SerOption::as_ptr_elem) ? SerOption::as_ptr : SerOption::none;
        const auto& aPtr     = get_ptr(ary); // reference to ary if it's a pointer; &ary otherwise
        switch ( ser.mode() ) {
        case serializer::MAP:
            serialize_array_map(
                ser, &(*aPtr)[0], elem_opt, SIZE, new ObjectMapContainer<T>(aPtr), serialize_array_map_element<ELEM_T>);
            break;
 
        case serializer::UNPACK:
            if constexpr ( std::is_pointer_v<OBJ_TYPE> ) {
                // for pointers to fixed arrays, we allocate the storage
                if constexpr ( std::is_array_v<T> )
                    ary = reinterpret_cast<OBJ_TYPE>(new std::remove_extent_t<T>[std::extent_v<T>]);
                else
                    ary = reinterpret_cast<OBJ_TYPE>(new T);
            }
            [[fallthrough]];
 
        default:
            // TODO: How to handle array-of-array
            // is_trivially_serializable_excluded_v<ELEM_T> can be added to exclude arrays-of-arrays from the fast path
            if constexpr ( is_trivially_serializable_v<ELEM_T> )
                ser.raw(&(*aPtr)[0], sizeof(ELEM_T) * SIZE);
            else
                serialize_array(ser, &(*aPtr)[0], elem_opt, SIZE, serialize_array_element<ELEM_T>);
            break;
        }
    }
};
 
} // namespace pvt
 
// Serialize fixed arrays and pointers to them
template <typename ELEM_T, size_t SIZE>
class serialize_impl<ELEM_T[SIZE]> : pvt::serialize_impl_fixed_array<ELEM_T[SIZE], ELEM_T, SIZE>
{
    SST_FRIEND_SERIALIZE();
};
 
template <typename ELEM_T, size_t SIZE>
class serialize_impl<std::array<ELEM_T, SIZE>> : pvt::serialize_impl_fixed_array<std::array<ELEM_T, SIZE>, ELEM_T, SIZE>
{
    SST_FRIEND_SERIALIZE();
};
 
template <typename ELEM_T, size_t SIZE>
class serialize_impl<ELEM_T (*)[SIZE]> : pvt::serialize_impl_fixed_array<ELEM_T (*)[SIZE], ELEM_T, SIZE>
{
    SST_FRIEND_SERIALIZE();
};
 
template <typename ELEM_T, size_t SIZE>
class serialize_impl<std::array<ELEM_T, SIZE>*> :
    pvt::serialize_impl_fixed_array<std::array<ELEM_T, SIZE>*, ELEM_T, SIZE>
{
    SST_FRIEND_SERIALIZE();
};
 
// Serialize dynamic arrays
template <typename ELEM_T, typename SIZE_T>
class serialize_impl<pvt::array_wrapper<ELEM_T, SIZE_T>>
{
    void operator()(pvt::array_wrapper<ELEM_T, SIZE_T>& ary, serializer& ser, ser_opt_t opt)
    {
        ser_opt_t  elem_opt = SerOption::is_set(opt, SerOption::as_ptr_elem) ? SerOption::as_ptr : SerOption::none;
        const auto mode     = ser.mode();
        size_t     size     = 0;
 
        if ( mode != serializer::UNPACK )
            size = get_array_size(ary.size, "Serialization Error: Array size in SST::Core::Serialization::array() "
                                            "cannot fit inside size_t. size_t should be used for array sizes.\n");
 
        if ( mode == serializer::MAP ) {
            if constexpr ( !std::is_void_v<ELEM_T> )
                pvt::serialize_array_map(ser, ary.ptr, elem_opt, size,
                    new ObjectMapArray<ELEM_T, SIZE_T>(ary.ptr, ary.size), pvt::serialize_array_map_element<ELEM_T>);
            else
                ser.binary(ary.ptr, ary.size);
            return;
        }
 
        // TODO: How to handle array-of-array
        // is_trivially_serializable_excluded_v<ELEM_T> can be added to exclude arrays-of-arrays from the fast path
        if constexpr ( std::is_void_v<ELEM_T> || is_trivially_serializable_v<ELEM_T> )
            ser.binary(ary.ptr, ary.size);
        else {
            ser.primitive(ary.size);
            if ( mode == serializer::UNPACK ) {
                size = get_array_size(ary.size, "Serialization Error: Array size in SST::Core::Serialization::array() "
                                                "cannot fit inside size_t. size_t should be used for array sizes.\n");
                ary.ptr = new ELEM_T[size];
            }
            pvt::serialize_array(ser, ary.ptr, elem_opt, size, pvt::serialize_array_element<ELEM_T>);
        }
    }
 
    SST_FRIEND_SERIALIZE();
};
 
/**
   Version of serialize that works for copying raw pointers (only
   copying the value of the pointer.  Note that this is only useful
   if the value is going to be sent back to the originator, since it
   won't be valid on the other rank.
 */
template <typename ELEM_T>
struct serialize_impl<pvt::raw_ptr_wrapper<ELEM_T>>
{
    void operator()(pvt::raw_ptr_wrapper<ELEM_T>& a, serializer& ser, ser_opt_t UNUSED(opt)) { ser.primitive(a.ptr); }
    SST_FRIEND_SERIALIZE();
};
 
} // namespace SST::Core::Serialization
 
#endif // SST_CORE_SERIALIZATION_IMPL_SERIALIZE_ARRAY_H