Program Listing for File Scheduler.h

↰ Return to documentation for file (include/Karana/SOADyn/Scheduler.h)

/*
 * Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
 *
 * NOTICE TO USER:
 *
 * This source code and/or documentation (the "Licensed Materials") is
 * the confidential and proprietary information of Karana Dynamics Inc.
 * Use of these Licensed Materials is governed by the terms and conditions
 * of a separate software license agreement between Karana Dynamics and the
 * Licensee ("License Agreement"). Unless expressly permitted under that
 * agreement, any reproduction, modification, distribution, or disclosure
 * of the Licensed Materials, in whole or in part, to any third party
 * without the prior written consent of Karana Dynamics is strictly prohibited.
 *
 * THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
 * KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 * BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
 * FITNESS FOR A PARTICULAR PURPOSE.
 *
 * IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
 * INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
 * OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
 *
 * U.S. Government End Users: The Licensed Materials are a "commercial item"
 * as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
 * only as a commercial end item under the terms of this license.
 *
 * Any use of the Licensed Materials in individual or commercial software must
 * include, in the user documentation and internal source code comments,
 * this Notice, Disclaimer, and U.S. Government Use Provision.
 */

/**
 * @file
 * @brief Contains the declarations for the Scheduler class.
 */

#pragma once
#include "Karana/SOADyn/TimedEvent.h"
#include <vector>

namespace Karana::Dynamics {
    namespace kc = Karana::Core;
    namespace km = Karana::Math;

    /**
     * @class Scheduler
     * @brief The schedule class for the state propagator
     */
    class Scheduler {
        // Friend access to reschedule events at new time.
        friend class StatePropagator;

      public:
        /**
         * @brief Register a TimedEvent.
         * @param timed_event - The TimedEvent to register.
         * @param curr_time - The current time. Used for error checking.
         */
        void registerTimedEvent(const kc::ks_ptr<TimedEvent> &timed_event,
                                const km::Ktime &curr_time);

        /**
         * @brief Unregister a TimedEvent.
         * @param name - The name of the TimedEvent.
         * @param pre_hop - Whether this is a pre_hop timed event or not.
         * @param okay_not_exists - If true, then do not error out if a timed event by this name
         * does not exist with the given pre_hop setting, otherwise, error our if the given event
         * is not found.
         */
        void
        unregisterTimedEvent(std::string_view name, bool pre_hop, bool okay_not_exists = false);

        /**
         * @brief Determine whether a TimedEvent with the given name exists.
         *
         * @param name - The name of the TimedEvent.
         * @param pre_hop - Whether this is a pre_hop timed event or not.
         * @returns true if a TimedEvent with the given name and pre_hop setting exists, false
         * otherwise.
         */
        bool hasRegisteredTimedEvent(std::string_view name, bool pre_hop) const;

        /**
         * @brief Execute all the pre-hop events for the provided time.
         * @param t - The time to execute all pre-hop events for.
         */
        void executePreHopEvents(const km::Ktime &t);

        /**
         * @brief Execute all the post-hop events for the provided time.
         * @param t - The time to execute all post-hop events for.
         */
        void executePostHopEvents(const km::Ktime &t);

        /**
         * @brief Get the next explicit hop end time.
         * @returns The next explicit hop end time.
         */
        km::Ktime getNextExplicitHopEndTime() const;

        /**
         * @brief Dump info about the Scheduler to a string.
         * @param prefix - Prefix to prepend to each line of the dump string.
         * @returns A string with the dump info.
         */
        std::string dumpString(std::string_view prefix) const;

      private:
        /**
         * @brief Reschedule all events for a new time.
         *
         * This finds the closest appropriate event time for each event to
         * the new_time, and reschedules the event for that time.
         *
         * @param new_time The new time to reschedule all events for.
         * @param time_moved_backward true if the time moved backward, false otherwise.
         */
        void _rescheduleAllEventsForNewTime(const km::Ktime &new_time, bool time_moved_backward);

        /// Heap that tracks the pre-hop timed events.
        std::vector<kc::ks_ptr<TimedEvent>> _pre_hop_timed_events;

        /// Heap that tracks the pre-hop timed events.
        std::vector<kc::ks_ptr<TimedEvent>> _post_hop_timed_events;

        /// Guard against adding to the front of _pre_hop_timed_events while looping over it
        bool _executing_before = false;

        /// Guard against adding to the front of _pre_hop_timed_events while looping over it
        bool _executing_after = false;
    };
} // namespace Karana::Dynamics