SkillExecutionHandle.h

Go to the documentation of this file.

/**
 * This file is part of ArmarX.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @author     Fabian Reister ( fabian dot reister at kit dot edu )
 * @date       2025
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
#include <map>
#include <memory>
#include <optional>
#include <vector>
 
#include "RobotAPI/libraries/skills/core/SkillID.h"
#include <RobotAPI/libraries/skills/core/SkillExecutionID.h>
#include <RobotAPI/libraries/skills/core/SkillStatusUpdate.h>
 
namespace armarx::skills
{
 
    using SkillProxyPtr = std::unique_ptr<class SkillProxy>;
 
    /**
    * @brief RAII handle for a running subskill.
    *
    * Represents an asynchronously started subskill. The handle owns the
    * information required to control and query the subskill (a SkillProxy and
    * the subskill's execution id). To ensure that the subskill is properly
    * cleaned up, the handle should be destroyed (or explicitly abort()/join())
    * before the parent skill exits.
    *
    * The handle provides:
    *  - join(): block until the subskill terminates and get its terminated status
    *  - abort(): request asynchronous abortion of the subskill
    *
    * Copies of the handle will each hold their own proxy+execution id (shallow copies
    * of the proxy). Destruction of any handle will trigger a best-effort abort request;
    * therefore lifetime management should be done carefully by the caller.
    */
    class SkillExecutionHandle
    {
    public:
        /**
        * @brief Construct a handle for an executing subskill.
        * @param proxy A SkillProxy configured to control the subskill.
        * @param executionId The execution id returned when starting the subskill.
        */
        SkillExecutionHandle(SkillProxyPtr proxy, skills::SkillExecutionID executionId);
 
        /**
        * @brief Destructor requests cleanup of the subskill.
        *
        * As a safety measure, the destructor issues an asynchronous abort request
        * for the associated subskill. This is a best-effort request and may be
        * a no-op if the subskill already finished. If the caller needs to wait
        * for the subskill to finish cleanly, call join() before destruction.
        */
        ~SkillExecutionHandle();
 
        /**
        * @brief Block until the subskill terminates and return its status.
        *
        * This call will block the caller until the subskill execution finishes.
        * On success it returns a TerminatedSkillStatusUpdate describing the final
        * state of the subskill. If the subskill information cannot be retrieved
        * an empty optional may be returned (depending on SkillProxy semantics).
        *
        * @return optional containing TerminatedSkillStatusUpdate if available.
        */
        std::optional<TerminatedSkillStatusUpdate> join();
 
        /**
        * @brief Request an asynchronous abort of the subskill.
        *
        * This sends an abort request to the subskill but does not wait for it
        * to terminate. Use join() to wait for completion after calling abort()
        * if synchronous behavior is required.
        */
        bool abortAsync();
 
        /**
        * @brief Get the current execution status of the subskill.
        *
        * @return optional containing SkillStatusUpdate if available.
        */
        std::optional<SkillStatusUpdate> getExecutionStatus();
 
        const skills::SkillExecutionID& executionId() const;
 
    private:
        SkillProxyPtr proxy_;
        skills::SkillExecutionID executionId_;
 
        bool isJoined_ = false;
    };
 
    namespace util
    {
        struct JoinAllResult
        {
            operator bool() const;
 
            std::vector<armarx::skills::SkillExecutionID> failedSkillExecutionIDs() const;
            std::vector<armarx::skills::SkillID> failedSkillIDs() const;
 
            using UpdatesMap = std::map<armarx::skills::SkillExecutionID,
                                        std::optional<armarx::skills::TerminatedSkillStatusUpdate>>;
 
            UpdatesMap updates;
        };
 
        // Helper to extract raw pointer from any supported type
        template <typename T>
        SkillExecutionHandle*
        to_raw_ptr(T* ptr) noexcept
        {
            return ptr;
        }
 
        template <typename T>
        SkillExecutionHandle*
        to_raw_ptr(const std::unique_ptr<T>& ptr) noexcept
        {
            return ptr.get();
        }
 
        template <typename T>
        SkillExecutionHandle*
        to_raw_ptr(const std::shared_ptr<T>& ptr) noexcept
        {
            return ptr.get();
        }
 
        JoinAllResult joinAll(const std::vector<armarx::skills::SkillExecutionHandle*>& handles);
        JoinAllResult joinAll(const std::vector<std::unique_ptr<SkillExecutionHandle>>& handles);
        JoinAllResult joinAll(const std::vector<std::shared_ptr<SkillExecutionHandle>>& handles);
 
        // Variadic wrapper
        template <typename... Args>
        JoinAllResult
        joinAllAny(Args&&... args)
        {
            static_assert(
                (... && (std::is_convertible_v<decltype(to_raw_ptr(std::forward<Args>(args))),
                                               SkillExecutionHandle*>)),
                "All arguments to joinAll must be SkillExecutionHandle pointers or smart "
                "pointers");
 
            std::vector<SkillExecutionHandle*> rawHandles{to_raw_ptr(std::forward<Args>(args))...};
            return static_cast<JoinAllResult (*)(const std::vector<SkillExecutionHandle*>&)>(
                joinAll)(rawHandles);
        }
    } // namespace util
 
 
} // namespace armarx::skills