oneshotManager.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_ONESHOTMANAGER_H
#define SST_CORE_ONESHOTMANAGER_H
 
#include "sst/core/action.h"
#include "sst/core/sst_types.h"
#include "sst/core/ssthandler.h"
 
#include <cinttypes>
#include <map>
#include <string>
#include <utility>
#include <vector>
 
namespace SST {
 
class Simulation;
 
namespace Core {
 
// Forward declare OneShotManager
class OneShotManager;
 
// General using for these classes
using TimeStamp_t = std::pair<SimTime_t, int>;
 
 
class OneShot : public Action
{
public:
 
    /**
       Base handler for OneShot callbacks.
    */
    using HandlerBase = SSTHandlerBase<void, void>;
 
    /**
       Used to create checkpointable handlers for OneShot.  The callback function is
       expected to be in the form of:
 
         void func()
 
       In which case, the class is created with:
 
         new OneShot::Handler<classname, &classname::function_name>(this)
 
       Or, to add static data, the callback function is:
 
         void func(dataT data)
 
       and the class is created with:
 
         new OneShot::Handler<classname, &classname::function_name, dataT>(this, data)
     */
    template <typename classT, auto funcT, typename dataT = void>
    using Handler = SSTHandler<void, void, classT, dataT, funcT>;
 
    template <typename classT, auto funcT, typename dataT = void>
    using Handler2 [[deprecated(
        "The name Handler2 has been deprecated and will be removed in SST 17. Please rename Handler2 to Handler.")]]
    = SSTHandler<void, void, classT, dataT, funcT>;
 
    using HandlerList_t = std::vector<OneShot::HandlerBase*>;
 
    OneShotManager* manager;
    HandlerList_t&  handlers;
    TimeStamp_t     time;
 
    OneShot(TimeStamp_t time, OneShotManager* manager, HandlerList_t& handlers) :
        manager(manager),
        handlers(handlers),
        time(time)
    {
        setDeliveryTime(time.first);
        setPriority(time.second);
    }
 
    ~OneShot() {}
 
    void execute() override;
};
 
 
/**
   Manages the OneShot actions for the core.  This allows handlers to
   be registered with the core that will be called at a specific time
   and priority.
*/
class OneShotManager
{
 
    using HandlerVectorMap_t = std::map<TimeStamp_t, std::pair<OneShot::HandlerList_t, bool>>;
 
public:
 
    /////////////////////////////////////////////////
 
    /** Create a new One Shot for a specified time that will callback the
        handler function.
        Note: OneShot cannot be canceled, and will always callback after
              the timedelay.
    */
    OneShotManager(Simulation* sim);
    ~OneShotManager();
 
    /** Add a handler to be called on this OneShot Event */
    template <class classT, auto funcT, typename dataT>
    void registerRelativeHandler(SimTime_t trigger_time, int priority, classT* obj, dataT metadata)
    {
        OneShot::HandlerBase* handler = new OneShot::Handler<classT, funcT, dataT>(obj, metadata);
        registerHandlerBase(trigger_time, priority, true, handler);
    }
 
    /** Add a handler to be called on this OneShot Event */
    template <class classT, auto funcT>
    void registerRelativeHandler(SimTime_t trigger_time, int priority, classT* obj)
    {
        OneShot::HandlerBase* handler = new OneShot::Handler<classT, funcT>(obj);
        registerHandlerBase(trigger_time, priority, true, handler);
    }
 
    /** Add a handler to be called on this OneShot Event */
    template <class classT, auto funcT, typename dataT>
    void registerAbsoluteHandler(SimTime_t trigger_time, int priority, classT* obj, dataT metadata)
    {
        OneShot::HandlerBase* handler = new OneShot::Handler<classT, funcT, dataT>(obj, metadata);
        registerHandlerBase(trigger_time, priority, false, handler);
    }
 
    /** Add a handler to be called on this OneShot Event */
    template <class classT, auto funcT>
    void registerAbsoluteHandler(SimTime_t trigger_time, int priority, classT* obj)
    {
        OneShot::HandlerBase* handler = new OneShot::Handler<classT, funcT>(obj);
        registerHandlerBase(trigger_time, priority, false, handler);
    }
 
 
private:
    friend class OneShot;
 
    HandlerVectorMap_t handler_vector_map_;
    Simulation*        sim_ = nullptr;
 
    /**
       Registers a handler for delivery at the specified time
     */
    void registerHandlerBase(SimTime_t trigger_time, int priority, bool relative, OneShot::HandlerBase* handler);
 
    /**
       Schedules the first entry in handler_vector_map_ if it is not
       already scheduled.
     */
    void scheduleNextOneShot();
 
    // Function that will be called when a oneshot is done calling its
    // handlers.  This allows the OneShotManager to clean things up
    // and schedule the next OneShot
    void oneshotCallback(TimeStamp_t time, OneShot* oneshot);
};
 
} // namespace Core
} // namespace SST
 
#endif // SST_CORE_ONESHOTMANAGER_H